# Project Management Requirements 9-15 Audit

Date: 2026-07-15

## Architecture Reviewed

- Project model: `WorkContainer` is the project/container model and already owns organization, department, programme, manager, dates, status, progress, attachments, comments, work items, status histories, budgets, expenses, risks, and issues.
- Activity/task model: `WorkItem` already supports planned/actual/forecast dates, baseline start/end fields, estimated/actual effort, progress, assignees, updates, dependencies, milestone approval fields, attachments, comments, time entries, and contribution records.
- Users and roles: `User` uses Spatie permissions, organization/department scope, positions, task assignments, and helper methods for project-manager behavior.
- Organization structure: `Organization`, `Department`, `Program`, and `OrganizationPosition` exist and are organization-scoped.
- Audit: `ActivityLog` and `LogsActivity` exist and should be reused.
- Notifications: `WorkTenantNotificationService` and `WorkTenantSystemNotification` exist and should be reused.
- Reports: `ReportController`, `ReportDatasetService`, and `ReportFilterService` already support JSON/CSV/XLSX/PDF exports and tenant-aware report filters.
- Dashboards: `DashboardStatisticsService`, `DashboardController`, `OrganizationDashboardController`, `ProjectDashboardController`, and static pages under `appl/` power live dashboard data.
- Frontend: static app shell under `appl/` uses `WorkTenantAPI`, `WorkTenantRender`, `WorkTenantOrganizationShell`, `WorkTenantAdminShell`, and member shell classes.
- Current permissions: Spatie permissions are seeded in `RolesAndPermissionsSeeder`.

## Requirement 9: Resource and Workload Management

Existing functionality:
- Users belong to organizations and departments.
- Work items can be assigned to users via `WorkItemAssignee`.
- Time entries track actual effort after approval.
- Organization positions track employee assignment history.

Partially implemented:
- Assignment exists, but no capacity, availability, leave, allocation percentage, or over-allocation logic exists.
- Project managers can assign tasks but cannot plan resource capacity at project level.

Missing:
- Resource profiles, calendars/exceptions, leave/unavailability, project resource allocations, workload service, allocation validation, reports, dashboards, and My Capacity views.

Reusable code:
- `User`, `OrganizationPosition`, `WorkContainer`, `WorkItem`, `WorkItemAssignee`, `WorkItemTimeEntry`, `ActivityLog`, notifications, reports.

Risks:
- Cross-organization allocation must be blocked.
- Capacity and cost fields need permission restrictions.
- Organization administrators may view resources but should not automatically receive project edit powers.

Required changes:
- Add resource profile/calendar/allocation tables and service-driven capacity calculations.
- Add `resources.*` and `resource-allocations.*` permissions.
- Add API endpoints, reports, dashboard summary data, and tests for over-allocation, leave reduction, and tenant isolation.

## Requirement 10: Project Baselines and Variance

Existing functionality:
- Work items have `baseline_start_date` and `baseline_end_date`.
- Project status histories and budget versions exist.

Partially implemented:
- Date fields exist but no immutable approved baseline snapshot exists.

Missing:
- Formal baseline records, snapshot payload, workflow, single active baseline rule, variance service, reports, and baseline UI.

Reusable code:
- `WorkContainer`, `WorkItem`, `ProjectBudget`, `ProjectExpense`, `WorkItemTimeEntry`, lifecycle service, reports, activity logs.

Risks:
- Mutable project/task fields cannot be treated as historical baseline.
- Only one current baseline must be active per project.

Required changes:
- Add project baselines with versioned snapshots, approval/activation workflow, variance calculations, reports, and tests.

## Requirement 11: Change-Control Management

Existing functionality:
- Project lifecycle transitions exist.
- Budgets, expenses, risks, and issues are separately managed.

Partially implemented:
- No traceable change request controls material project changes.

Missing:
- Change requests, impact assessment, approval, implementation tracking, controlled application of approved changes, reports, and dashboard metrics.

Reusable code:
- `WorkContainer`, `Program`, `ProjectBaseline`, activity logs, notifications, approval structures.

Risks:
- Approved changes must preserve previous values and should not silently mutate projects unless implementation is explicitly performed.

Required changes:
- Add change requests, impact fields, approval/implementation actions, permissions, reports, and tests.

## Requirement 12: Project Approval and Governance

Existing functionality:
- Project statuses include approval-oriented lifecycle states.
- Milestone approval exists for work items.
- Escalations and activity logs exist.

Partially implemented:
- Project status cannot be changed directly, but there is no configurable approval workflow.

Missing:
- Approval workflows, workflow steps, approval requests/decisions, governance bodies, governance decisions, delegations, proposal submission flow, reports, and dashboards.

Reusable code:
- `ProjectLifecycleService`, `ProjectStatus`, notifications, activity logs, Spatie roles/permissions.

Risks:
- Organization approval authority must not imply project editing authority.
- Delegation must be dated and scoped.

Required changes:
- Add generic approval workflow tables and services that can be reused by baselines, change requests, and projects.

## Requirement 13: Quality Management

Existing functionality:
- Outputs, indicators, work-item evidence, risks, issues, attachments, comments.

Partially implemented:
- Outputs/indicators support M&E but are not a deliverable acceptance workflow.

Missing:
- Quality plans, deliverables, acceptance criteria, quality reviews, non-conformances, corrective/preventive actions, quality reports, and dashboard metrics.

Reusable code:
- `Output`, `WorkItem`, `Attachment`, `ProjectIssue`, `ActivityLog`, reports.

Risks:
- Tasks must not be treated as deliverables.
- Mandatory criteria must block acceptance unless an authorized exception exists.

Required changes:
- Add quality module tables, workflow actions, permissions, reports, and tests.

## Requirement 14: Stakeholder Management

Existing functionality:
- Users, organizations, partner links, comments, notifications.

Partially implemented:
- External organizations and project partners exist, but no stakeholder analysis or engagement register exists.

Missing:
- Stakeholder register, matrix classification, engagement plan, interactions, confidentiality controls, reports, dashboard metrics.

Reusable code:
- `User`, `Organization`, `WorkContainerPartnerLink`, `ActivityLog`, attachments, reports.

Risks:
- Sensitive stakeholder data must not be exposed to unauthorized contributors.
- Stakeholders may link to users or organizations, but must remain project-specific.

Required changes:
- Add stakeholder tables, classification service logic, interaction records, permissions, reports, and tests.

## Requirement 15: Communication Planning and Management

Existing functionality:
- Comments, notifications, attachments, email notification support.

Partially implemented:
- Notifications exist but no communication plan, schedule, delivery log, or meeting management exists.

Missing:
- Communication plans/items/actions/logs, scheduled due communications, meeting records, meeting decisions/action items, reports, dashboard metrics.

Reusable code:
- `WorkTenantNotificationService`, `WorkItem`, attachments, comments, reports.

Risks:
- Do not create a second task system for meeting actions; link action items to `WorkItem`.
- Private communication content must be permission restricted.

Required changes:
- Add communication tables, due-action generation, delivery records, meeting management, permissions, reports, dashboard metrics, and tests.

## Shared Implementation Decisions

- Reuse `WorkContainer` as the project model and `Program` as the programme model.
- Reuse `ActivityLog` for audit trails and add action names per workflow.
- Reuse Spatie permissions; do not create another permission system.
- Reuse `ReportFilterService`/`ReportDatasetService` for screen reports and exports.
- Use direct `organization_id` columns on new tables for tenant isolation, validated against parent project organization.
- Use policies or controller authorization backed by permissions and organization checks.
- Use JSON snapshots for baseline version 1 to avoid duplicating every detail table immediately; validate and version the snapshot payload.
- Use existing `WorkItem` for meeting action items; meeting records may link to work items.

## Testing Gaps

- No tests exist for resource profile/allocation/workload.
- No tests exist for formal baselines and variance.
- No tests exist for change control.
- No generic approval workflow tests exist.
- No quality deliverable/criteria/non-conformance tests exist.
- No stakeholder confidentiality or interaction tests exist.
- No communication plan/action/log/meeting tests exist.
- Existing dashboard/report tests must be extended after each module adds live metrics.