PSA/ee/docs/plans/2026-03-18-per-phase-task-statuses/SCRATCHPAD.md

# Scratchpad — Per-Phase Task Statuses

- Plan slug: `per-phase-task-statuses`
- Created: `2026-03-18`

## Decisions

- (2026-03-18) **Fallback behavior**: `phase_id IS NULL` in `project_status_mappings` = project-level defaults. Phases without custom statuses automatically fall back. No data migration needed.
- (2026-03-18) **Cross-phase task movement**: same status name → keep it; no match + source open → first open by display_order; no match + source closed → first closed by display_order. Rationale: simple, predictable, avoids modal dialogs during drag-drop.
- (2026-03-18) **Phase creation default**: New phases inherit project defaults automatically (no rows needed — fallback handles it). User explicitly opts into custom statuses. Rationale: zero-cost setup, opt-in complexity.
- (2026-03-18) **Template phases**: Add `template_phase_id` to `project_template_status_mappings` — same nullable FK pattern. Rationale: consistency with main table approach.
- (2026-03-18) **No feature flag**: Feature is additive and opt-in. Until a user configures phase-specific statuses, behavior is identical to before.

## Discoveries / Constraints

- (2026-03-18) Both `project_status_mappings` and `project_phases` are Citus-distributed on `tenant`, colocated with `tenants`. FK constraints must use composite keys `(tenant, phase_id)`.
- (2026-03-18) `project_status_mappings` has primary key `(tenant, project_status_mapping_id)`. The FK to `project_phases` must reference `(tenant, phase_id)`.
- (2026-03-18) Implemented `F001` in `server/migrations/20260318100000_add_phase_id_to_project_status_mappings.cjs`: added nullable `phase_id` plus a composite FK on `(tenant, phase_id)` to `project_phases`. Although the feature text mentions `project_phases(phase_id)`, the schema only exposes `(tenant, phase_id)` as a valid referenced key.
- (2026-03-18) Implemented `F002` in the same migration file by indexing `(tenant, project_id, phase_id)`. Keeping the column and its lookup index together avoids ordering issues during rollout and rollback.
- (2026-03-18) Implemented `F003` in `server/migrations/20260318101000_add_template_phase_id_to_project_template_status_mappings.cjs`: added nullable `template_phase_id` with a composite FK on `(tenant, template_phase_id)` because `project_template_phases` is also keyed that way.
- (2026-03-18) Implemented `F004` with `ee/server/migrations/citus/20260318102000_fix_phase_status_mapping_foreign_keys.cjs` and marked the CE migrations `transaction: false`. The EE migration inspects existing FK definitions and only drops/recreates phase-related constraints when they are not tenant-scoped, which is safer for already-distributed tables than assuming a fixed constraint name.
- (2026-03-18) `moveTaskToPhase()` in `projectTaskActions.ts` (lines 972-1033) currently only resolves statuses for **cross-project** moves. Same-project moves preserve the original status mapping ID. This must change to also handle same-project cross-phase moves when phases have different statuses.
- (2026-03-18) `ProjectDetail.tsx` is the orchestrator that passes `statuses={projectStatuses}` to KanbanBoard (line ~2406). It fetches statuses once at project level. This is the critical wiring point.
- (2026-03-18) Client portal has its own separate components (`ClientKanbanBoard`, `ClientTaskListView`, `ProjectDetailView`) — they do NOT reuse MSP-side KanbanBoard. Separate data action `getClientProjectStatuses()`.
- (2026-03-18) Status change events (`PROJECT_STATUS_ADDED`, etc.) are published from `projectTaskStatusActions.ts`. They currently include `projectId` but not `phaseId`.
- (2026-03-18) `ProjectTaskStatusEditor.tsx` and `ProjectTaskStatusSelector.tsx` are used during project creation/editing. They may need to handle template-based phase statuses.
- (2026-03-18) Phase task CSV import (`IImportReferenceData.statusMappings`) resolves statuses at project level. Needs to resolve against phase-effective statuses.
- (2026-03-18) The `display_order` field's uniqueness scope changes from per-project to per-(project, phase). Need to ensure reordering logic scopes correctly.
- (2026-03-18) `TB01` is implemented as a migration contract test against migration source files rather than a live schema migration run. This keeps coverage fast while still locking down nullable columns, composite FK wiring, additive behavior, and the EE Citus companion repair.

## Progress Log

- (2026-03-18) `TB01` complete. Added `server/src/test/unit/migrations/perPhaseTaskStatusesMigration.contract.test.ts` to assert nullable `phase_id`/`template_phase_id`, additive migration behavior, CE phase index creation, and EE composite FK repair inputs. Verification: `cd server && npx vitest run src/test/unit/migrations/perPhaseTaskStatusesMigration.contract.test.ts`.
- (2026-03-18) `TB02` complete. Added `server/src/test/unit/interfaces/projectStatusPhaseId.contract.test.ts` to lock the shared and server `IProjectStatusMapping` / `ProjectStatus` contracts to an optional `phase_id` field. Verification: `cd server && npx vitest run src/test/unit/interfaces/projectStatusPhaseId.contract.test.ts`.
- (2026-03-18) `TB03` complete. Added `packages/projects/src/models/project.phaseStatusResolution.test.ts` with an in-memory Knex-like query harness to exercise `getProjectStatusMappings`, `getEffectiveStatusMappings`, and `getProjectTaskStatuses` across phase-specific overrides, fallback-to-default behavior, ordered results, and tenant isolation. Verification: `cd packages/projects && npx vitest run src/models/project.phaseStatusResolution.test.ts`.
- (2026-03-18) `TB04` complete. Added `packages/projects/src/actions/projectPhaseStatusActions.contract.test.ts` to pin the action-layer phase plumbing in `projectTaskStatusActions.ts` and `projectActions.ts`: phase-aware insert scope, phase/default filtering, phase-scoped reordering, and threading `phaseId` into effective status resolution. Verification: `cd packages/projects && npx vitest run src/actions/projectPhaseStatusActions.contract.test.ts`.
- (2026-03-18) `TB04` uses source-contract coverage rather than importing the action modules directly because the package-level Vitest config does not resolve server-only workspace packages like `@alga-psa/db`. The assertions target the concrete query branches and call sites that implement the phase behavior.
- (2026-03-18) `TB05` complete. Added `packages/projects/src/actions/projectPhaseStatusCopyRemove.contract.test.ts` to lock the copy/remove phase-status flows: cloning default mappings into a phase with preserved fields and remapping `project_tasks` to default mappings before deleting custom phase mappings. Verification: `cd packages/projects && npx vitest run src/actions/projectPhaseStatusCopyRemove.contract.test.ts`.
- (2026-03-18) `TB06` complete. Added `packages/projects/src/actions/projectTaskMovePhaseStatus.contract.test.ts` to pin the same-project status remapping helper and `moveTaskToPhase` branches: exact-name reuse, open/closed fallback selection, fallback-to-first behavior, and preservation of the existing cross-project remapping path. Verification: `cd packages/projects && npx vitest run src/actions/projectTaskMovePhaseStatus.contract.test.ts`.
- (2026-03-18) `TB07` complete. Added `packages/projects/src/components/phaseAwareProjectDetail.contract.test.ts` to pin phase-driven status refetching in `ProjectDetail`, phase-effective kanban/status-count derivations, `KanbanBoard` column rendering from `statuses` props, and phase-scoped status fetching in `TaskEdit` / `TaskQuickAdd`. Verification: `cd packages/projects && npx vitest run src/components/phaseAwareProjectDetail.contract.test.ts`.
- (2026-03-18) `TB08` complete. Added `packages/projects/src/components/settings/projects/projectTaskStatusSettingsPhase.contract.test.ts` to pin the status-scope selector, default/custom toggles, copy/revert flows, phase-aware `AddStatusDialog` wiring, and the last-status deletion guard enforced by `projectTaskStatusActions.ts`. Verification: `cd packages/projects && npx vitest run src/components/settings/projects/projectTaskStatusSettingsPhase.contract.test.ts`.
- (2026-03-18) `TB09` complete. Added `packages/client-portal/src/components/projects/clientPhaseStatuses.contract.test.ts` to pin client-portal phase-aware status resolution, phase-triggered refetching in `ProjectDetailView`, kanban column ordering from the selected phase’s statuses, and list-view grouping by effective status labels. Verification: `cd packages/client-portal && npx vitest run src/components/projects/clientPhaseStatuses.contract.test.ts`.
- (2026-03-18) Running the `packages/client-portal` Vitest target prints an unrelated coverage parser warning for `src/actions/client-portal-actions/client-billing.ts`, but the `TB09` test run still exits successfully with status code `0`.
- (2026-03-18) `TB10` complete. Added `packages/projects/src/components/project-templates/templatePhaseStatuses.contract.test.ts` to pin `template_phase_id` typing, phase-aware template status scope selection in `TemplateStatusManager` and `TemplateStatusColumnsStep`, and copying template phase-scoped mappings into `project_status_mappings` during project creation. Verification: `cd packages/projects && npx vitest run src/components/project-templates/templatePhaseStatuses.contract.test.ts`.
- (2026-03-18) `TB11` complete. Added `packages/projects/src/supportingSystemsPhaseStatuses.contract.test.ts` to pin phase-aware CSV import lookup generation, `phaseId` presence in project-status event payloads, and `ProjectTaskStatusEditor` / `ProjectTaskStatusSelector` handling of phase-scoped status selections during project/template setup. Verification: `cd packages/projects && npx vitest run src/supportingSystemsPhaseStatuses.contract.test.ts`.
- (2026-03-18) `TB12` complete. Added `packages/projects/src/backwardCompatibilityPhaseStatuses.contract.test.ts` to pin additive migration behavior, model fallback to project defaults when no phase overrides exist, default-scope behavior in the settings UI, and cascade FK cleanup for deleted phases. Verification: `cd packages/projects && npx vitest run src/backwardCompatibilityPhaseStatuses.contract.test.ts`.

## Commands / Runbooks

- Build shared packages: `npm run build:shared` (needed after type changes)
- Build projects package: `npx nx build projects`
- Run project tests: `npx vitest run` in `packages/projects/`
- Run migrations: `npm run migrate`
- Validate migration syntax quickly: `node -e "require('./server/migrations/20260318100000_add_phase_id_to_project_status_mappings.cjs')"`
- Validate template migration syntax quickly: `node -e "require('./server/migrations/20260318101000_add_template_phase_id_to_project_template_status_mappings.cjs')"`
- Validate EE Citus migration syntax quickly: `node -e "require('./ee/server/migrations/citus/20260318102000_fix_phase_status_mapping_foreign_keys.cjs')"`
- Citus migrations: applied via Argo workflows in EE environments

## Links / References

### Key Files — Database
- `server/migrations/20241008191930_create_project_status_mappings_table.cjs` — original table creation
- `ee/server/migrations/citus/20250805000018_distribute_remaining_tables.cjs` — Citus distribution of project_status_mappings
- `ee/server/migrations/citus/20250805000011_distribute_project_tables.cjs` — Citus distribution of project_phases
- `server/migrations/20251119000000_add_project_templates.cjs` — template status mappings table

### Key Files — Types
- `packages/types/src/interfaces/project.interfaces.ts` — IProjectStatusMapping (L37-50), ProjectStatus (L151-165)
- `server/src/interfaces/project.interfaces.ts` — duplicate interfaces

- (2026-03-18) Implemented `F005` by adding `phase_id?: string` to `IProjectStatusMapping` in both shared and server-local interface copies. The duplicate interface files still need to stay in sync manually.
- (2026-03-18) Implemented `F006` by adding `phase_id?: string` to `ProjectStatus` in the same two interface files so the flattened status DTO can carry its scope through actions and UI props.

### Key Files — Models & Actions
- `packages/projects/src/models/project.ts` — getProjectStatusMappings, getProjectTaskStatuses, addProjectStatusMapping
- `packages/projects/src/actions/projectTaskStatusActions.ts` — addStatusToProject, getProjectStatusMappings, reorderProjectStatuses
- `packages/projects/src/actions/projectActions.ts` — getProjectTaskStatuses (L1123-1134)
- `packages/projects/src/actions/projectTaskActions.ts` — moveTaskToPhase (L938-1120), updateTaskStatus

- (2026-03-18) Implemented `F007` by changing `ProjectModel.getProjectStatusMappings()` to accept `phaseId?: string | null`; omitted/null now explicitly means project defaults (`phase_id IS NULL`) rather than “all mappings for the project.” That keeps legacy callers stable once phase-specific rows exist.
- (2026-03-18) Implemented `F008` with `ProjectModel.getEffectiveStatusMappings()`, which first looks for phase-scoped mappings and only falls back to project defaults when none exist. This keeps callers from having to manually merge or filter both scopes.
- (2026-03-18) Implemented `F009` by threading `phaseId` through `ProjectModel.getProjectTaskStatuses()` and copying `mapping.phase_id` onto the returned status objects. Model callers can now request the effective status list for a specific phase without reproducing fallback logic.
- (2026-03-18) Implemented `F010` by extending `addStatusToProject()` with optional `phaseId`, storing `phase_id` on insert, and scoping the `display_order` lookup to either the target phase or project defaults. This prevents new phase statuses from inheriting order positions from unrelated scopes.
- (2026-03-18) Implemented `F011` by extending the action-layer `getProjectStatusMappings()` with the same scope rule as the model: `phaseId` fetches that phase’s rows, and no `phaseId` fetches only project defaults. That avoids leaking all phase rows into the existing settings UI.
- (2026-03-18) Implemented `F012` by extending `reorderProjectStatuses()` with optional `phaseId` and constraining each update to the matching phase/default scope. This protects phase-specific boards from reordering the wrong mapping set.
- (2026-03-18) Implemented `F013` by adding `copyProjectStatusesToPhase(projectId, phaseId)`. It validates phase ownership, treats an already-customized phase as idempotent, and copies only project-default mappings (`phase_id IS NULL`) into the phase while preserving ordering, visibility, and status references.
- (2026-03-18) Implemented `F014` by adding `removePhaseStatuses(phaseId)` and remapping affected tasks before deletion. The replacement rule already follows the PRD’s status-resolution order: same name first, then first target status with the same open/closed state, then final fallback to the first default status.
- (2026-03-18) Implemented `F015` by extending the public `getProjectTaskStatuses()` action and its internal helpers with optional `phaseId`, switching them onto `ProjectModel.getEffectiveStatusMappings()`, and carrying `phase_id` into the returned `ProjectStatus` DTOs.
- (2026-03-18) Implemented `F016` in `moveTaskToPhase()` by splitting same-project cross-phase moves from the existing cross-project branch, fetching target phase-effective mappings, and preserving intent via same-name matches when the original mapping ID is not valid in the destination phase.
- (2026-03-18) Implemented `F017` by upgrading the same-project phase move fallback: if no same-name mapping exists and the source status is open, the task now lands in the first open target status by `display_order` instead of the first arbitrary column.
- (2026-03-18) Implemented `F018` by making the fallback symmetric for closed work: if a closed task has no same-name match in the destination phase, `moveTaskToPhase()` now selects the first closed target status before falling back to the first overall column.
- (2026-03-18) Implemented `F019` by leaving the original cross-project move branch intact and isolating the new remapping logic to same-project cross-phase moves only. This keeps legacy project-to-project behavior stable while enabling phase-aware remapping where the PRD requires it.

### Key Files — MSP UI
- `packages/projects/src/components/ProjectDetail.tsx` — orchestrator, passes statuses to KanbanBoard (L2401-2406), phase selection (L186), task filtering (L346-425)
- `packages/projects/src/components/KanbanBoard.tsx` — receives statuses as prop
- `packages/projects/src/components/TaskStatusSelect.tsx` — status dropdown
- `packages/projects/src/components/settings/projects/ProjectTaskStatusSettings.tsx` — status config UI
- `packages/projects/src/components/settings/projects/AddStatusDialog.tsx` — add status dialog
- `packages/projects/src/components/ProjectTaskStatusEditor.tsx` — project creation status setup
- `packages/projects/src/components/ProjectTaskStatusSelector.tsx` — status selection for project setup

- (2026-03-18) Implemented `F021` by making `ProjectDetail.tsx` refetch `getProjectTaskStatuses(projectId, selectedPhase.phase_id)` whenever the selected phase changes, while resetting to the initial project-level statuses if no phase is selected.
- (2026-03-18) Implemented `F022` by deriving kanban counts from a lookup of the currently effective phase statuses, sorting visible columns by `display_order`, and ignoring tasks whose mapping IDs are not part of the selected phase’s effective status set.
- (2026-03-18) Implemented `F023` with a minimal prop-boundary change: `ProjectDetail.tsx` now passes `visibleKanbanStatuses` into `KanbanBoard`, so the board renders from the selected phase’s effective status columns directly.
- (2026-03-18) Implemented `F024` by making `TaskEdit` and `TaskQuickAdd` fetch phase-effective statuses for their active phase, including same-project phase switches. That ensures `TaskStatusSelect` receives the correct status list via props even when the editor phase differs from the surrounding view state.
- (2026-03-18) Implemented `F025` in `ProjectTaskStatusSettings` with a scope selector at the top of the panel. `Project Defaults` is the first option, followed by each project phase loaded from `getProjectMetadata(projectId)`.
- (2026-03-18) Implemented `F026` with phase-level mode controls in `ProjectTaskStatusSettings`: each selected phase now shows `Use project defaults` versus `Custom statuses`, with control enablement derived from whether that phase currently has custom mappings.
- (2026-03-18) Implemented `F027` by wiring the phase-default state to a `Copy from project defaults` action that calls `copyProjectStatusesToPhase(projectId, phaseId)` and reloads the scoped mappings after success.
- (2026-03-18) Implemented `F028` by making the `Use project defaults` path confirm before calling `removePhaseStatuses(phaseId)`, then reloading the phase scope so the UI falls back to the project-level mappings.
- (2026-03-18) Implemented `F029` by extending `AddStatusDialog` with optional `phaseId` and passing that through to `addStatusToProject(projectId, statusData, phaseId)`, so a phase can start custom status configuration without copying the defaults first.
- (2026-03-18) Implemented `F030` by separating client-portal phase loading from status loading in `ProjectDetailView`. Statuses are now refetched with `getClientProjectStatuses(projectId, selectedPhaseId)` whenever the selected phase changes.
- (2026-03-18) Implemented `F031` with a minimal client-kanban boundary change: `ClientKanbanBoard` now sorts and renders columns directly from the phase-specific `statuses` prop supplied by `ProjectDetailView`.
- (2026-03-18) Implemented `F032` by having client task rows carry effective status metadata from `project_status_mappings` and grouping `ClientTaskListView` by `custom_name || status_name` in mapping `display_order`. This keeps each phase’s list view aligned with its effective status columns.

### Key Files — Client Portal
- `packages/client-portal/src/components/projects/ProjectDetailView.tsx` — orchestrator
- `packages/client-portal/src/components/projects/ClientKanbanBoard.tsx` — kanban view
- `packages/client-portal/src/components/projects/ClientTaskListView.tsx` — list view
- `packages/client-portal/src/actions/client-portal-actions/client-project-details.ts` — getClientProjectStatuses

- (2026-03-18) Implemented `F020` by extending `getClientProjectStatuses()` with optional `phaseId` and the same “phase first, else project defaults” lookup pattern used on the MSP side. The query now also coalesces custom and standard statuses so client portal reads remain backward compatible.

### Key Files — Templates
- `packages/projects/src/components/project-templates/TemplateStatusManager.tsx`
- `packages/projects/src/components/project-templates/wizard-steps/TemplateStatusColumnsStep.tsx`

- (2026-03-18) Implemented `F033` by threading optional `template_phase_id` into the template status-mapping interfaces and wizard type definitions. The schema column from `F003` is now representable in runtime objects and wizard state.
- (2026-03-18) Implemented `F034` by adding a scope selector to `TemplateStatusManager` with `Template Defaults` plus every template phase. The manager now resolves effective statuses per selected phase, can copy template defaults into a phase, can revert a phase back to template defaults, and scopes add/reorder operations by `template_phase_id` in `projectTemplateActions.ts`.
- (2026-03-18) Supporting work for `F034`: `createTemplateFromProject()`, `duplicateTemplate()`, and `applyTemplate()` now preserve phase-scoped template/project status mappings through `template_phase_id` and `phase_id` when those maps already exist. This keeps template editor scope changes coherent with later template application.
- (2026-03-18) Implemented `F035` by making `TemplateStatusColumnsStep` phase-aware in wizard state. The step now scopes mappings by `template_phase_id`, supports copying defaults into a phase, uses defaults as fallback when a phase has no overrides, and clears stale task mappings when a scoped column is removed or reset.
- (2026-03-18) Supporting work for `F035`: `TemplateTasksStep` and `TemplateReviewStep` now resolve effective statuses per selected phase, and `createTemplateFromWizard()` / `updateTemplateFromEditor()` create phases before status mappings so phase-scoped wizard mappings can be persisted with real `template_phase_id` values.
- (2026-03-18) Implemented `F036` by finishing phase-aware template application in `applyTemplate()`. Project status mappings copied from a template now retain the source `template_phase_id -> phase_id` relationship, and task fallback logic chooses the first effective status for the target phase instead of a project-global first column.
- (2026-03-18) Implemented `F037` in the phase/task import pipeline. `getImportReferenceData()` and both validation paths now build `statusLookupByPhase` from each existing phase’s effective statuses, `groupRowsIntoPhases()` resolves `status_mapping_id` against the row’s target phase, and the import dialog threads those phase-aware lookups through regrouping after agent resolution.
- (2026-03-18) Implemented `F038` by adding optional `phaseId` to all published project-status mutation events in `projectTaskStatusActions.ts`. Add, update, delete, and reorder events now preserve scope so downstream listeners can distinguish project defaults from phase-specific changes.
- (2026-03-18) Implemented `F039` by making `ProjectTaskStatusEditor` and `ProjectTaskStatusSelector` phase-aware primitives. Both components now preserve optional `phaseId` / `phase_id` scope when fetching, adding, deduplicating, and reordering statuses, so a template-driven project creation flow can pass phase-scoped statuses through the same UI without flattening them back to project defaults.
- (2026-03-18) Implemented `F040` as a cross-cutting compatibility guarantee rather than a new code path. Every new phase-aware entry point now falls back to `phase_id IS NULL` project defaults when no phase override exists, which preserves existing-project behavior until a phase is explicitly customized.

### Key Files — Import / Events
- `packages/types/src/interfaces/phaseTaskImport.interfaces.ts` — IImportReferenceData

## Open Questions

- None currently — all design decisions agreed upon.