TL - Cross-Cutting Checklist

[MuhammadKhalilzadeh]

Focus: architecture, team enablement, and delivery guardrails. These items are not hands-off management tasks; each has a concrete deliverable that you can ship, review, or automate so the rest of the team moves faster and safer.

---

• 1. Unify API documentation and close the swagger/code drift

  The codebase has 560 endpoints, but swagger.yaml covers only ~280, endpoints.ts covers 187, and swagger.generated.yaml is stale. Pick one source of truth: either generate endpoints.ts from swagger.yaml or serve Swagger UI directly from the backend. Then add a CI check that fails when a route is added without a matching OpenAPI operation. Start by fixing the 26 endpoints that enforce authenticateJWT but lack a bearerAuth security spec, and the four assessment endpoints that are documented but commented out in assessment.route.ts.

  This is a force-multiplier: once docs and code are aligned, Debora’s contract tests, frontend DTO generation, and onboarding all become cheaper. Document the chosen approach in Servers/CLAUDE.md and the PR template so new endpoints cannot drift again.

  Acceptance: Single source of truth is chosen and wired; CI check fails on undocumented routes; 26 missing security specs added; stale generated docs are regenerated automatically or removed.

• 2. Lead a cross-tenant security review and mandate an isolation test matrix

  There is currently no test that proves one organization cannot read another’s data. Define a cross-tenant isolation policy: which entity types must be scoped, which roles can bypass, and how service-to-service calls must propagate organizationId. Build a reusable test matrix in Servers/tests/integration/tenant-isolation/ and make it a required CI gate for any new domain that stores organization-scoped data.

  Pair with each developer to make sure their current and next tasks respect the policy. Write a one-page security runbook in docs/technical/security/tenant-isolation.md that explains the policy, common mistakes (e.g., forgetting organization_id in raw SQL), and how to add a new entity to the matrix.

  Acceptance: Isolation matrix covers projects, files, users, risks, and tasks; policy document is reviewed by the team; CI gate documented; you sign off on at least three PRs that add new scoped entities.

• 3. Define a shared role/permission contract between Node, AIGateway, and EvalServer

  Role name-to-ID mapping is currently hardcoded in AIGateway/src/utils/auth.py, duplicated in the Node JWT middleware, and absent from EvalServer. Create a single source of truth for roles and permissions — either a shared JSON file in shared/auth/roles.json or generated types from the database — and consume it from all three services. Add startup validation in AIGateway and EvalServer that fails fast if the contract does not match the Node backend.

  This contract becomes the foundation for the frontend <RequireRole> route wrapper and the backend authorize() middleware. Update Servers/CLAUDE.md, AIGateway/CLAUDE.md, and EvalServer/CLAUDE.md with the new contract and examples of how to add a role.

  Acceptance: Single source of truth exists; all three services load roles from it; startup mismatch fails fast; frontend and backend middlewares use the same definitions; docs updated.

• 4. Establish code-ownership rules and update the PR template

  As the team grows, reviews are becoming inconsistent. Define code-ownership rules for the major domains (Servers/controllers/*, Clients/src/presentation/pages/*, AIGateway/src/*, EvalServer/src/*, shared design tokens, migrations) and record them in CODEOWNERS or docs/internal/ownership.md. Update the PR template to require: linked issue, passing typecheck, test evidence, StyleGuide update if UI changes, OpenAPI update if route changes, and a note about cross-tenant impact.

  Then review the open PR backlog and apply the new template retroactively to the most active PRs. Use the review round to coach each developer on the new expectations rather than just blocking merges.

  Acceptance: Ownership file or CODEOWNERS is merged; PR template updated and used on new PRs; at least five existing PRs are re-reviewed against the new rules; team is briefed.

• 5. Execute the Phase 0 AI testing checklist and publish a remediation report

  docs/PHASE0_AI_TESTING_GUIDE.md contains a 20-item happy-path checklist that is entirely unchecked. Run through it end-to-end, recording which items pass, which fail, and which are blocked by missing features. For each failure, create a concise bug card with reproduction steps, expected behavior, and a proposed owner.

  Publish the results as docs/internal/phase0-test-report-YYYY-MM-DD.md and present them in the next team sync. Prioritize the failures that block Phase 1 features and assign them before the next sprint starts.

  Acceptance: All 20 checklist items are marked pass/fail/skip; report is merged; follow-up tasks are filed and assigned; team sync presentation delivered.

• 6. Build a public AI Implementation Plan tracker and roadmap

  The AI Implementation Plan targets 263 tools across multiple phases, but progress is only visible in source code and spreadsheets. Create a lightweight tracker — either a markdown page in docs/ or a read-only UI page at Clients/src/presentation/pages/AIAdvisorRoadmap — that maps implemented tools to planned tools by domain and phase. Expose the data through a backend endpoint that reads the current registry and the static plan manifest.

  This tracker is not just reporting; it helps you spot which domains are behind schedule and which dependencies are blocking multi-agent and proactive-AI work. Review it weekly in standups and update it as tasks close.

  Acceptance: Tracker lists implemented vs planned tools by domain; backend endpoint exists and is tested; page or doc is accessible to the team; you update it weekly during the sprint.

• 7. Audit migration hygiene and enforce timestamp ordering in CI

  Several migration issues are already documented: 20260408171819 fails retroactively because a later migration removed a constraint, EvalServer drops public.alembic_version unconditionally, and AIGateway migrations assume Node-created tables exist. Audit all active migration directories (Servers/database/migrations, AIGateway/src/database/migrations, EvalServer/src/database/migrations) for ordering risks, destructive ops, and missing rollback/down scripts.

  Add a CI check that rejects new migration timestamps that are not strictly after the latest applied migration, and require every new migration to have a down step unless explicitly exempted. Document the migration runbook in Servers/CLAUDE.md and EvalServer/CLAUDE.md.

  Acceptance: Audit report lists risks and fixes; CI timestamp check merged; known broken migrations are marked applied or fixed; runbook reviewed by the team.

• 8. Implement CI gates for typecheck, coverage, bundle size, and i18n

  The production frontend build currently skips TypeScript checking, coverage thresholds are set to 10%, there is no bundle-size budget, and the i18n strict audit fails with 650 gaps per language. Decide on realistic short-term targets (e.g., typecheck enforced, coverage thresholds raised to 30%, bundle budget introduced, i18n audit made informational until gaps are fixed) and implement them in .github/workflows/.

  Make each gate fail with a clear message and, where possible, produce an artifact (coverage report, bundle visualizer, i18n gap list). Announce the new gates in the team channel and coach developers on how to read the artifacts.

  Acceptance: Typecheck runs in CI before deployment; coverage thresholds raised; bundle-size step produces an artifact; i18n policy documented; no gate is silently ignored.

• 9. Drive the observability strategy: Sentry, structured logging, and PII redaction

  Multiple TODOs in the frontend error boundaries and the secure logger ask for an error-tracking sink. Pick a monitoring service (Sentry or DataDog), create a project account or integration, and wire it into Clients/src/presentation/components/Dashboard/WidgetErrorBoundary.tsx, DashboardErrorBoundary.tsx, and MegaDropdownErrorBoundary.tsx. At the same time, audit Servers/utils/logger/logHelper.ts and the AIGateway logging paths to ensure tokens, API keys, and PII are redacted before being written to logs or sent to the monitoring service.

  On the backend, harden the /health endpoint in Servers/app.ts so it returns a generic degraded status and logs specifics server-side, preventing reconnaissance. Document the monitoring setup and redaction rules in docs/technical/observability.md.

  Acceptance: Error tracking receives frontend errors; logger redaction rules are in place; /health returns generic status; observability doc is merged; team knows how to query errors.

• 10. Run a full-stack rotation and pair-programming schedule

  One of the best ways to grow T-shaped developers is intentional cross-layer pairing. Schedule a two-week rotation where each backend-focused developer pairs on a frontend task and each frontend-focused developer pairs on a backend task. For example, Harsh pairs with Inna on responsive design, Inna pairs with Harsh on service refactoring, Aryaman pairs with Debora on contract tests, and Debora pairs with Aryaman on optimistic updates.

  Create a shared calendar and a lightweight pairing log in docs/internal/pairing-log.md. At the end of the rotation, run a 30-minute retro to capture what each person learned and which pairing patterns should become routine. This deliverable is about team capability, not just code output.

  Acceptance: Rotation schedule published and followed; pairing log has at least four entries; retro notes captured; at least one follow-up improvement to team process is adopted.