Task-Flow-Tracker

Imported from Veeresh111/Task-Flow-Tracker (AGENTS.md). Install upstream with npx skills add Veeresh111/Task-Flow-Tracker. Copyright stays with the author.

AGENTS.md — Progress Log

Goal

Enterprise-grade HRMS/ATS with role security, identity verification, assessment proctoring, and full recruitment lifecycle automation.

Evidence Requirements

Every claim must be backed by:

• Before/after code: Show the affected lines in both states
• Build verification: npm run build output
• Test artifacts: Playwright report, junit.xml, HTML report, screenshots, traces, console logs
• End-to-end demo: Workflow executed with real database records showing the change
• Git status: Confirm no unintended files changed
• Full-repo search: For secrets/keys, search every directory (src, supabase, tests, scripts, docs, env examples)

Pipeline Status

Verification Workflow (Mandatory)

1. Pre-Implementation Analysis: Why, Root Cause, Affected Files/Components/Tables/Roles/APIs/Workflows, Side Effects, Regression Risk, Security/Performance/Business Impact
2. Impact Analysis: Map all dependent pages, components, APIs, DB tables, workflows
3. Implementation Plan: Present analysis + plan for user approval BEFORE writing code
4. Implementation: Small batches only, with before/after code shown
5. Post-Implementation Analysis: Files changed, functions modified, every old feature still works
6. Regression: Build + full test suite with artifacts
7. Evidence: Test report, screenshots/traces, git diff, end-to-end demo with real DB data

Auto-Fix Policy

• CRITICAL bugs (route misrouting, auth bypass, security holes) → analyze + fix immediately
• Business behavior changes (payroll calculations, approval workflows, analytics formulas, AI scoring, etc.) → produce analysis + plan, wait for user approval before any code changes
• Fixes must never: remove/rewrite/disable existing features, change business rules, alter UI behavior without approval

Modification Policy

1. Do NOT remove existing features
2. Do NOT replace existing business logic without evidence
3. Do NOT rename database columns or tables without approval
4. Do NOT change UI behavior unless fixing a verified bug
5. Before every implementation: root cause analysis + evidence + business impact + risk assessment + regression risk + implementation plan
6. After implementation: files changed + DB objects changed + tests executed + before/after comparison + regression verification + rollback plan

Planned Phases

Phase A: Code Audit ✅ (Complete)

• 60 findings: 10 CRITICAL, 18 HIGH, 22 MEDIUM, 10 LOW
• 7 CRITICAL fixes applied (C-01 through C-06, C-09)
• 2 HIGH fixes applied (H-04: Chat delete auth, H-11: Employee projects filter)
• 2 additional fixes: C-10 (TL/Employee Chat delete auth)

Phase B1: Headcount/Payroll RPC Enforcement ⬜ (NEXT)

Standardize all pages to use get_enterprise_metrics() RPC as single source of truth.

• Fix Admin Dashboard "Monthly Payroll Liability" (actually annual CTC)
• Remove HR Dashboard 65000 hardcoded fallback
• Fix Admin Analytics to prefer RPC over custom calculation
• Fix Admin AI Insights currency format (USD → INR)
• Standardize headcount: "Total Headcount" vs "Base Employees" distinction

Phase B2: Unified Payroll Formula ⬜

Single calculatePayslipBreakdown(annualCTC) utility shared by all 4 payroll pages.

• One formula, one implementation, consistent payslip across all roles

Phase B3: Performance Score Unification ⬜

Single calculatePerformanceScore() function shared by all dashboards.

• Eliminate 3 different scoring algorithms

Phase B4: Task Completion Normalization ⬜

Shared isTaskCompleted() utility with exact-match logic.

Phase B5: Hire Metrics ⬜

Update RPC + pages to count hires from candidate_onboarding instead of profiles.created_at.

Phase C: Business Logic Validation ⬜ (after B-series)

Verify every business rule across domains: Verify every business rule across domains:

Recruitment

• Can HR reject after interview?
• Can HR reopen a closed application?
• Duplicate application prevention
• Expired assessment handling
• Offer revocation workflow
• Candidate withdrawal flow
• Multiple offers handling

Payroll

• Joining mid-month calculation
• Leaving mid-month settlement
• Loss of Pay (LOP) deduction
• Paid leave inclusion
• Overtime computation
• Bonus and increment processing
• Tax, PF, ESI, Professional Tax deductions
• Final settlement on exit

Attendance

• Missing punch handling
• Double punch detection
• Overnight shift calculation
• Weekend/holiday rules
• Remote/office/hybrid policies

Phase C: AI Output Validation ⬜ (NEXT)

For every AI-generated value, answer:

• Which database rows were used?
• Which SQL query produced them?
• Which formula was applied?
• Which records contributed?
• Which assumptions were made?
• Which values are estimated?
• Confidence score
• Reproducibility

Outputs failing these checks must be labeled "AI-generated commentary" not authoritative metric.

Phase D: Database Integrity Audit ⬜ (NEXT)

• Every foreign key validated
• Every cascade rule correct
• Every unique constraint applied
• Every index present
• Every trigger verified
• Every RPC reviewed
• Every view/materialized view checked
• Every RLS policy tested
• Every storage bucket secured
• Every Edge Function reviewed
• Every cron/scheduled task documented

Phase E: Load Testing ⬜ (FUTURE)

Test with enterprise volumes:

• 10,000 employees, 50,000 tasks, 100,000 work logs
• 500 concurrent users, 20 HR, 100 Team Leads
• 2 million notifications, 1 million chat messages, 100 GB documents

Measure: dashboard load time, payroll gen time, AI response time, DB latency, memory/CPU, query performance.

Implemented Phases

Phase 1: Role Security Hardening ✅

• Register.tsx: Removed role selector — only shows "Candidate / Applicant" info box. No way to self-select HR/Admin/Employee roles.
• auth.ts: Hard-rejects any non-candidate signup role. Always forces role: 'candidate' in profile insert.
• types/index.ts: Fixed UserRole type to include 'hr' | 'candidate' | 'payroll' | 'manager'.
• Employee Invite Page (/hr/EmployeeInvite.tsx): HR/Admin can create employee invitation profiles with role/department.
• Employee Activation Page (/public/EmployeeActivation.tsx): Invited employees can check their invitation status and get instructions to activate.
• Routes added: /employee-activation, /admin/employee-invite, /hr/employee-invite

Phase 2: Candidate Identity Enrollment ✅

• IdentityEnrollment component (/components/identity/IdentityEnrollment.tsx): Webcam capture + photo upload for identity verification.
• Candidate Identity Page (/candidate/Identity.tsx): Dedicated page in candidate dashboard for identity enrollment.
• Stores photo in profiles.avatar_url column.
• Shows status: enrolled (green) or not enrolled (amber warning).
• Route added: /candidate/identity

Phase 3: Assessment Proctoring (In-Browser) ✅

• useProctoring hook (/hooks/useProctoring.ts): Real-time detection of:
  • Tab switching (visibilitychange API)
  • Window blur/focus loss
  • Copy/paste prevention
  • Right-click prevention
  • Full-screen exit detection
  • DevTools shortcut prevention
• Violation engine: warning counting with flagging at threshold-2 and auto-disqualify at threshold.
• Logs to proctoring_logs table (table may not exist in live DB — graceful error handling).

Phase 4: Face Verification ✅

• useFaceVerification hook (/hooks/useFaceVerification.ts): face-api.js integration for:
  • Face detection during identity enrollment (live feedback in webcam preview)
  • Face descriptor extraction and storage in localStorage
  • Face matching at assessment entry (compares live face to enrolled descriptor)
  • Periodic face re-verification every 30s during assessment
  • Graceful degradation if face-api.js models fail to load (CDN)
• IdentityEnrollment updated to show face detection confidence score
• AssessmentAccess.tsx updated: face check before exam entry + periodic re-checks

Phase 5: Jitsi Meet Integration ✅

• JitsiMeetRoom component (/components/interview/JitsiMeetRoom.tsx): Vanilla Jitsi External API integration
  • Embeds Jitsi Meet iframe directly in interview page
  • Configures audio muting, toolbar, interface (no watermark)
  • Uses meet.jit.si domain; room name sanitized from meeting_link
  • Shows loading spinner while connecting
• CandidateInterviews.tsx updated:
  • Jitsi links detected automatically (contains meet.jit.si or jitsi)
  • Opens embedded modal instead of new tab
  • Fullscreen overlay with video controls
  • onLeave callback cleans up on close
  • Non-Jitsi links still open in new tab (backward compatible)

Phase 6: Enterprise Tests ✅

• 10 tests in src/test/e2e/enterprise-features.spec.ts:
  • Register page only allows candidate role
  • Registration flow creates candidate-only profiles
  • Employee activation page loads
  • Employee invitation page loads (admin)
  • Identity enrollment page loads (candidate)
  • New routes resolve (not blank)
  • Proctoring prevents copy/paste/right-click
  • Auth service rejects non-candidate signup
  • Admin-created employee invitation

RLS Self-Role-Change Bypass — FIXED ✅

Fix applied via trigger migration (supabase/migrations/20260626000001_fix_rls_role_escalation.sql):

• Created trg_prevent_self_role_change trigger on profiles table
• Trigger compares OLD.role with NEW.role; if different and user is not admin, raises Permission denied
• Tests confirm all 5 role-elevation targets (admin, hr, team_lead, payroll, manager) are now blocked
• RLS test at src/test/e2e/rls-vulnerability-audit.spec.ts proves the fix works

Application-Level RLS Mitigation ✅

• auth.ts: verifyAndResetRole() function — if user_metadata.registered_role != profiles.role and role is elevated, auto-resets to candidate
• ProtectedRoute.tsx: Second line of defense — re-verifies role on every route navigation
• Logs security events and creates notifications on role reset

Code Audit Fixes Applied

C-01: Dual Source Tree Deleted (CRITICAL)

• Removed flowtracker/flowtracker/ legacy directory containing unsecure Register.tsx with role-elevation vulnerability
• Verification needed: Which Vite root/tsconfig/package.json/main.tsx is active? Git status clean? Any imports broken?

C-02: Team-Lead Payroll — DB-Backed (CRITICAL)

• Replaced role-based hardcoded salaries (65k/95k/125k) with profiles.payroll_ctc
• Employee Payroll was already fixed in prior session

C-03: Removed Fake Revenue/Profit (CRITICAL)

• Removed teamMembers.length * 65000 * 1.8 fabricated metrics and all associated cards/attributes from team-lead AIInsights

C-04: Relabeled Heuristic Rating (CRITICAL)

• "AI Performance Rating" → "Task Performance Score" in employee AIInsights
• Removed all "AI ratings" language from labels and descriptions

C-05: Hardcoded API Key — Legacy-Only

• Fallback key AQ.Ab8... only existed in deleted legacy tree
• Verification needed: Full-repo search for this key across ALL directories (src, supabase, tests, scripts, docs)

C-06: adminCreateUser — Not Present

• Canonical src/lib/auth.ts has no adminCreateUser function
• Legacy tree had it with anon key — deleted with C-01

C-09: Punitive AI Prompt Removed

• Removed "if Hours > 11.5, severely penalize score below 40 and scold employee" from DashboardLayout

H-04: Message Delete Authorization

• Added sender_id === userId check to deleteMessage in Chat.tsx
• Only own messages deletable

H-11: Employee Projects Filtered

• Changed from select('*') all projects → filtered by profile.team_lead_id

Known Issues

1. offer_letters.candidate_name has no DEFAULT — requires explicit name on insert
2. candidate_onboarding FK mismatch — 11+ pending migrations need applying before production
3. proctoring_logs table doesn't exist in live DB (not blocking)
4. Apply form UI submit fails in headless — tests use API fallback which works

New Files

Modified Files (Code Audit)

Supabase Context

• Supabase project: [REDACTED - set via Vercel env vars]
• Storage buckets exist: resumes ✅ bgc_docs ✅ avatars ✅ (offer_letters ❌)
• 11+ pending migrations (14 applied on remote, 11+ local-only incl. RLS trigger + offer schema)
• Admin: [REDACTED - set via Vercel env vars]
• HR: [REDACTED - set via Vercel env vars]
• RLS role-change bypass FIXED via trigger

Production Checklist

• No fake or placeholder data anywhere
• Every displayed number traceable to DB or documented business formula
• Every AI insight clearly distinguished from deterministic calculations
• Complete candidate → employee → exit lifecycle validated
• Complete payroll lifecycle validated (join, leave, LOP, OT, bonus, tax, PF, ESI, settlement)
• All role-based permissions verified
• No RLS bypasses
• No hardcoded secrets (full-repo grep confirmed)
• No N+1 query issues
• No orphaned database records
• All automations (payroll, notifications, reports) tested
• Full regression suite passing with evidence (reports + logs + screenshots + traces)
• Performance/load testing completed
• Security review completed