# Project Management Gap Audit

This audit is based on the current WorkTenant Laravel application. `WorkContainer` is the project-equivalent model, `WorkItem` is the task/activity model, Spatie Laravel Permission is the authorization system, and `ActivityLog` is the reusable audit trail.

## 1. Project Lifecycle Management

- Exists: `work_containers.status` stores project state, policies protect basic create/update/delete, and project dashboards read status.
- Partial: completion status can be sent through the normal update endpoint, but status is free text and invalid transitions are not blocked.
- Missing: controlled transitions, transition reasons, approval/override metadata, status history, lifecycle-specific permissions, and prevention of operational edits on closed/archived projects.
- Reuse: `WorkContainerPolicy`, `ActivityLog`, `WorkContainerController`, and dashboard/report services.
- Required database changes: project status history table and completion metadata columns.
- Security concerns: transition actions must enforce tenant scope and project-management permissions server-side, not only via UI controls.

## 2. Completion-Date Handling

- Exists: `work_containers.completion_date` is nullable, creation validation prohibits it, and update currently auto-fills it for `completed` or `closed`.
- Partial: the backend already prevents completion date on create, but the transition is not controlled and completion can be reached without a lifecycle audit record.
- Missing: completion notes, completed-by user, progress override, schedule variance, and reopen behavior history.
- Reuse: existing date columns and report/dashboard date rendering.
- Required database changes: completion metadata on `work_containers`, plus project status history.
- Security concerns: only authorized users may complete/reopen projects, and overrides must be logged.

## 3. Actual Effort and Time Logging

- Exists: `work_items.estimated_effort` and `work_items.actual_effort` columns exist.
- Partial: actual effort can be typed directly through the Quick Task form/API, which is not reliable.
- Missing: time-entry records, contributor submission workflow, approval/rejection, overlap validation, derived actual effort, and effort reporting.
- Reuse: `WorkItemPolicy`, work-item assignments, reports, and activity logs.
- Required database changes: `work_item_time_entries`.
- Security concerns: users must only log time against assigned/authorized tasks inside their organization; rejected entries must not affect actual effort.

## 4. Project Scheduling

- Exists: planned/actual task dates, project planned dates, parent-child work items, dependencies, and a Gantt-style frontend.
- Partial: dependencies validate self-reference, cross-organization links, and cycles, but not same-project membership or dependency audit fields.
- Missing: dependency organization/project/creator columns, baseline date preservation, schedule calculations, and stronger schedule reporting.
- Reuse: `WorkItemDependencyController`, `ProjectIntelligenceService`, and existing Gantt rendering.
- Required database changes: dependency metadata and optional baseline date columns.
- Security concerns: dependency endpoints must prevent cross-tenant and cross-project IDOR.

## 5. Milestone Management

- Exists: `WorkItem.item_type`, `milestone_weight`, planned/actual dates, attachments through updates.
- Partial: milestones can be represented as work items but have no dedicated statuses or approval workflow.
- Missing: milestone submission/approval/rejection, completion criteria, evidence requirement, actual achievement date, owner approval, and milestone reports.
- Reuse: `WorkItem`, work-item assignments, attachments, comments, and `WorkItemPolicy`.
- Required database changes: milestone-specific columns on work items are sufficient for v1.
- Security concerns: only assigned contributors may submit, and only authorized managers may approve/reject.

## 6. Project Budgeting and Cost Management

- Exists: reports have a placeholder budget report based on project weights only.
- Partial: there is no real budget/expense data model.
- Missing: budget categories, approved budgets, budget lines, expenses, approval workflow, cost calculations, budget revisions, attachments, and reports.
- Reuse: project scope, activity logs, reports, attachments.
- Required database changes: budget categories, project budgets, budget lines, project expenses, budget revisions.
- Security concerns: financial approvals must not be available to ordinary contributors, and all records must be organization/project scoped.

## 7. Risk Management

- Exists: escalations and dashboard “risk radar” derived from blocked/stalled work.
- Partial: escalation is useful but is not a dedicated risk register.
- Missing: risk model, likelihood/impact/residual scoring, response strategy, owner, review workflow, closure, heat-map data, and risk reports.
- Reuse: activity logs, attachments, comments, organization/project scoping.
- Required database changes: `project_risks`.
- Security concerns: risk owners may update assigned risks, but rating changes/closure require explicit permissions.

## 8. Issue Management

- Exists: escalations can describe active problems, but risks and issues are not separated.
- Partial: no dedicated issue register exists.
- Missing: issue assignment, investigation, resolution, closure, reopening, root cause, target/actual resolution dates, related risk/task links, and issue reports.
- Reuse: activity logs, attachments, comments, organization/project scoping.
- Required database changes: `project_issues`.
- Security concerns: users must not access issues outside their organization or unauthorized projects.

## Cross-Cutting Findings

- Reports and dashboards already have extensible services and should be expanded rather than duplicated.
- Spatie permissions are already installed and must remain the single role/permission system.
- `ActivityLog` is sufficient for audit records when metadata includes previous/new values, reasons, and actor context.
- Static pages under `appl/` are the active frontend surface; UI work must update those files and `appl/assets/js/app.js`.