New_Micro_Learning/docs/phase-checklist.md

Phase Completion Checklist

This file is the execution record for the Master Prompt phases. An item is checked only after implementation and proportional verification. Passing tests alone does not make a product capability complete.

Phase 1 — Design System and Application Shells

Design foundations

• Semantic light/dark color tokens, typography, spacing, radii, elevation, motion, breakpoints, and z-index scales are implemented.
• FA/EN locale changes the document language and true RTL/LTR direction without hard-coded physical layout assumptions.
• Theme and locale preferences persist across reloads and respect the initial system preference.
• Reusable primitives exist for buttons, fields, validation, alerts, badges, loading/skeleton, empty, error, permission-denied, offline, modal, and toast feedback.
• Interactive controls have visible focus, disabled, pending, pressed, and error states with minimum 44px targets.

Application shells

• Designer shell contains the complete Master Prompt navigation and header actions.
• Super Admin shell contains the complete platform-operations navigation.
• Manager shell contains the complete team-management navigation.
• Learner shell is mobile-first and uses at most five labelled bottom-navigation destinations.
• Desktop sidebar, tablet collapse, and mobile drawer behavior work without horizontal overflow.
• Command palette opens with Ctrl/Cmd+K, is keyboard accessible, searches authorized navigation, and supports dismissal/focus restoration.
• Shell profile and organization labels are data-driven; no demo identity is presented as real user data.
• Route transitions move focus to main content and all shells provide skip navigation.

Phase 1 quality gates

• Component and shell tests pass.
• TypeScript strict typecheck passes.
• Lint passes.
• Production build passes.
• Visual review passes at 375px-equivalent CSS breakpoint, 768px, 1024px, and desktop in RTL and LTR.
• Reduced-motion and light/dark modes are reviewed.

Phase 2 — Authentication, Tenancy, and Organization Infrastructure

Backend

• Login, logout, current-user, forgot-password, reset-password, invitation acceptance, and disabled-account behavior are implemented.
• Auth responses expose the minimum safe identity, role, locale, timezone, organization context, permissions, and deployment capabilities.
• Auth and password endpoints have validation, privacy-safe errors, and rate limiting.
• Tenant context is resolved exclusively from the authenticated user and ignores client-supplied organization identifiers.
• Tenant-owned queries and route-model lookups used in this phase are organization scoped.
• Super Admin organization list/create/read/update endpoints exist without exposing tenant learning analytics.
• SaaS/On-Prem capabilities are served through the deployment abstraction.

Frontend

• Central typed API client handles bearer tokens, validation errors, unauthenticated responses, and abort signals.
• Auth session provider restores the current session and keeps remote identity out of Zustand.
• Login screen is complete, accessible, bilingual, responsive, and handles pending/success/failure.
• Forgot-password and reset-password screens are complete and privacy-safe.
• Invitation-acceptance screen is complete and validates token/name/password states.
• Protected routes redirect unauthenticated users and role guards reject unauthorized workspaces.
• Signed-in shell displays the real user and organization context.
• Logout revokes the current token and clears local session state.
• Organization administration screen consumes real APIs and implements loading, empty, populated, error, and permission-denied states.
• Deployment capabilities hide SaaS-only organization administration in On-Prem mode.

Phase 2 quality gates

• Backend auth, tenancy, organization authorization, and isolation tests pass.
• Frontend auth/provider/guard/form tests pass.
• Typecheck, lint, and production build pass.
• Login and recovery screens pass RTL/LTR and mobile visual review.
• No client-provided organization ID is trusted by authenticated tenant APIs.

Phase 3 — Users, Teams, Subscriptions, and Permissions

Backend

• User directory supports tenant-scoped search, role/status filters, pagination, and safe user payloads.
• Course Designers can update user role/status within allowed tenant boundaries; last active Designer protection is enforced.
• Invitations expose pending/expired status and can be resent or revoked without leaking tokens.
• Team APIs support list/create/read/update plus member and manager attach/detach with tenant validation.
• Manager reads remain restricted to managed teams and their members.
• Subscription API exposes dates, feature flags, seat/storage/AI quotas, and current usage without pricing logic.
• Seat quota is enforced consistently for invitations and activations.
• Central permission matrix is returned by the session and enforced server-side for every Phase 3 mutation.

Frontend

• Users screen uses real APIs with search, role/status filters, loading/empty/populated/error/permission states, and invitation workflow.
• Teams screen uses real APIs with create, details, member/manager assignment, removal, and responsive states.
• Subscription screen presents real plan dates, feature flags, quota usage, and accessible progress indicators.
• UI actions are permission-aware while backend authorization remains authoritative.
• Mutation pending/success/failure feedback is visible and accessible.
• Phase 3 tables/cards remain usable on mobile, tablet, RTL/LTR, and light/dark themes.

Phase 3 quality gates

• Backend users/teams/subscription/permission/quota tests pass.
• Frontend Users/Teams/Subscription tests pass.
• Typecheck, lint, and production build pass.
• Responsive and RTL/LTR visual review passes.
• No Phase 3 tenant resource can be accessed or mutated cross-tenant.

Phase 4 — Course Domain, Versions, Modules, and Lessons

Backend

• Course list supports tenant-scoped search, status filters, sorting, pagination, and safe summary payloads.
• Blank-course creation atomically creates Course, Draft Version 1, initial Module, and initial Lesson.
• Course workspace API exposes overview, ordered structure, and version history without learner analytics placeholders.
• Draft version metadata can be edited while Published versions remain immutable.
• Editing a Published version forks a complete new Draft version with stable source-version history.
• Module APIs support create/update/delete/reorder with contiguous positions and draft-only mutations.
• Lesson APIs support create/update/delete/reorder/move with contiguous positions and draft-only mutations.
• Existing blocks are copied when a Published version is forked and remain linked to the new version hierarchy.
• All Course, Version, Module, Lesson, and fork operations are tenant-scoped and permission-enforced.

Frontend

• Courses screen uses real APIs with search, status views, sorting, and loading/empty/populated/error/permission states.
• New Course screen presents exactly four creation paths and completes the Blank Course workflow.
• Future Template, Import, and AI paths are clearly unavailable without fake progress or generated results.
• Course Workspace provides Overview, Content, and Versions views backed by real API data.
• Content view supports module and lesson creation, rename, deletion, and ordering with visible mutation feedback.
• Published versions expose a clear “Create editable draft” action instead of direct editing.
• Course routes are deep-linkable, permission-aware, responsive, RTL/LTR-safe, and light/dark compatible.

Phase 4 quality gates

• Backend course/version/module/lesson authorization, immutability, ordering, fork, and tenant-isolation tests pass.
• Frontend Courses/New Course/Course Workspace tests pass.
• Typecheck, lint, formatting, and production build pass.
• Responsive RTL/LTR and light/dark visual review passes.
• No Phase 4 resource can be accessed or mutated cross-tenant.

Phase 5 — Builder Core

Backend and contracts

• Builder reads the canonical Course Version/Lesson structure through tenant-scoped APIs.
• Block creation supports an explicit insertion position and keeps lesson positions contiguous.
• Block duplication preserves the unified contract and creates an independent Draft copy.
• Module and Lesson duplication copy their nested Draft content without crossing tenant/version boundaries.
• Module and Lesson lock state is explicit and prevents protected structure/content mutations.
• All Builder mutations remain Draft-only, permission-enforced, revision-aware, and tenant-isolated.

Builder experience

• Builder uses the central authenticated API client and works with the real application session.
• RTL Builder layout provides Canvas, Course Structure, Block Library, and Inspector with functional collapsible panels.
• Toolbar provides functional Undo/Redo for persisted content edits and block ordering.
• Autosave exposes clear idle, saving, saved, and failed states with a retry path.
• Primary Heading, Text, and Key Point content can be edited inline on the Canvas.
• Insertion affordances between blocks open an accessible Block Picker at the selected position.
• Slash commands open the same Block Picker without creating a second block-selection system.
• Keyboard shortcuts support save, undo, redo, selection dismissal, and safe deletion.
• Drag-and-drop reordering has optimistic feedback, clear drop state, and keyboard-accessible move controls.
• Course Structure supports real lesson navigation plus module/lesson add, rename, duplicate, reorder, delete, and lock controls.
• Desktop, Tablet, and Mobile preview widths use the same canonical block renderer.
• Published versions are visibly read-only and never expose active mutation controls.
• Comments, collaboration, AI, learner preview, and publishing controls are labelled honestly as later-phase capabilities.

Phase 5 quality gates

• Backend insertion/duplication/locking/revision/immutability/tenant tests pass.
• Frontend history/autosave/inline editing/picker/shortcuts/panel tests pass.
• Typecheck, lint, formatting, and production build pass.
• Builder visual review passes at desktop, tablet, mobile preview, RTL/LTR, and light/dark states.
• No fake save, preview, collaboration, AI, or publishing result is presented as functional.

Later phases

Pre-Phase 7 Product Corrections

• Asset and video uploads accept files up to 2 GB in API validation and the local launcher PHP configuration.
• Content Library supports a compact row view and an exact 5 cm × 5 cm desktop card view.
• Workforce import accepts XLSX/CSV files with first name, last name, department, job level, direct manager, and email columns.
• Workforce import validates job levels, duplicate/ambiguous identities, tenant boundaries, seat quota, and applies changes atomically.
• Course cards are approximately 30% denser and preserve responsive behavior.
• Designers can select, replace, or remove a private image Asset as the Course cover.
• Selecting a Team manager automatically attaches that manager and their active direct reports.
• Teams screen presents consolidated metrics, search, structured manager/member groups, and clearer hierarchy details.
• Positive/confirmation actions use semantic green and destructive/negative actions use semantic red.
• Seeded Manager and Learner review accounts are documented and usable.
• User directory renders name, email, department, job position, manager, role, status, and actions in independent columns.
• User profiles can be edited with hierarchy-cycle and cross-tenant manager protection.
• Every Draft-safe Asset exposes deletion; used Draft references are detached atomically while Published references remain protected.
• Content cards keep title, size, usage count, and destructive action in non-overlapping regions.
• Image, video, audio, and PDF Assets open in an accessible preview dialog; unsupported documents offer a safe open/download path.
• Workforce import includes a real downloadable RTL XLSX template with manager-first sample rows.
• Backend and Frontend regression suites, typecheck, lint, formatting, production build, migrations, launcher check, API smoke tests, and visual review pass.

Phase 6 — Block System and Block Registry

Canonical block platform

• Backend and Frontend registries expose one unified Block contract: data, style, behavior, responsive, accessibility, capabilities, web behavior, and export compatibility.
• Registry validation covers every implemented non-assessment Phase 6 block and rejects unknown fields/types safely.
• Schema-version migration infrastructure can upgrade persisted Block data without silently rewriting Published versions.
• Builder availability is driven by Registry metadata and parity is protected by automated tests.
• Heading, Text, Quote, Key Point, Divider, and Button blocks are implemented.
• Image, Gallery, Video, Audio, Document, and Embed blocks are implemented with safe URL/file behavior.
• Flashcard, Accordion, Tabs, Timeline, Steps, Process, and Checklist blocks are implemented.
• Section, preset Columns, and Controlled Grid blocks are implemented with responsive stacking configuration.
• Phase 6 shipped no fake assessment interactions; the real assessment catalog is completed in Phase 7 below.

Editing and rendering

• Each registered block supplies its own Renderer, Editor configuration, validation schema, defaults, icon, and category without Builder-level type switches.
• Inspector Content, Design, and Behavior tabs are functional for the properties supported in Phase 6.
• Design controls persist alignment, width, spacing, background, border, and radius using controlled tokens.
• Behavior controls persist visibility, completion, animation, and Block lock state without claiming Player behavior before Phase 9.
• Accessibility controls persist alt text, labels, transcript/caption information, and decorative intent where applicable.
• Canonical renderers are reused by Builder preview widths and nested controlled layouts stack safely on mobile.
• Navigator supports locate/select plus visible/locked state and keyboard ordering alternatives.

Assets and learning mapping

• Tenant-scoped Asset API validates type, MIME, size, extension, filename, authorization, and private access.
• Asset list supports search/type filtering, preview metadata, and usage-reference counts.
• Used Draft assets can be detached and deleted atomically; Published references and cross-tenant assets remain protected.
• Content Library provides real upload, search, filter, preview, usage, empty/loading/error, and safe-delete states.
• Media Block editors select uploaded assets through one reusable Asset Picker.
• Reusable LearningMappingPanel lists direct Block mappings and searches taxonomy nodes by name/code/type.
• Designers can add and remove confirmed develops/practices/assesses/related mappings on Draft Blocks.
• Published and cross-tenant mapping mutations remain rejected; AI suggestions are not presented as confirmed mappings.

Phase 6 quality gates

• Backend Registry, schema, Asset validation/privacy/usage, mapping, authorization, and tenant-isolation tests pass.
• Frontend Registry/editor/renderer, Asset Library/Picker, Mapping Panel, Inspector, and responsive-layout tests pass.
• Typecheck, lint, backend formatting, and production build pass.
• Builder and Content Library visual review passes in RTL/LTR, light/dark, desktop/tablet/mobile states.
• start-dev.bat --check, authenticated API smoke tests, and temporary-service cleanup pass.
• No Phase 8 publishing or Phase 9 Player result is presented as functional.

Phase 7 — Assessments and Scenarios

Question bank and assessment authoring

• Tenant-scoped Question Bank supports create, edit, delete, search, type, difficulty, topic, tags, explanation, usage, and performance metadata.
• Single Choice, Multiple Choice, True/False, Matching, Sorting, Drag and Drop, and Hotspot question schemas are validated server-side.
• Assessments support reusable bank questions, direct question copies, ordering, random selection, pools, shuffling, passing score, attempt limit, feedback mode, and time limit.
• Draft assessment/question mutations are authorized, tenant-isolated, and rejected for Published Course Versions.
• Assessments and individual assessment questions support weighted taxonomy/competency mappings.

Scenarios and interactive blocks

• Scenario authoring supports context, choices, score, feedback, topic, difficulty, and tags.
• Branching Scenario visual authoring supports Scene, Question, Choice/Branch, and Result nodes.
• Branch graphs reject missing start nodes, broken targets, duplicate nodes, and unreachable nodes.
• Interactive Image and Before/After blocks are registered with real editors, renderers, schemas, and Asset references.
• Backend and Frontend Block registries expose the complete Phase 7 assessment/interaction catalog with validated defaults.

Phase 7 quality gates

• Question Bank, assessment settings, scenario graph, authorization, Published immutability, and tenant-isolation tests pass.
• Assessment Studio and Registry UI tests pass, including taxonomy mapping access.
• Full backend suite passes: 93 tests and 559 assertions.
• Full frontend suite passes: 11 files and 35 tests.
• Typecheck, lint, backend formatting, migrations, seed data, and production build pass.
• Visual review passes for Question Bank, assessment mapping, scenarios, users, Excel import, and both Content Library layouts.

Later phases

• Phase 7 — Assessments and scenarios
• Phase 8 — Publishing, assignments, and Learning Paths
• Phase 9 — Learner Player, PWA, and offline
• Phase 10 — Manager Workspace and Learner iOS Experience
• Phase 11 — Events, analytics, and Monitoring
• Phase 12 — Collaboration and realtime
• Phase 13 — AI Studio and ingestion
• Phase 14 — Export Center and certificates
• Phase 15 — Production hardening and deployment

Phase 8 — Publishing, Assignments, and Learning Paths

Publishing and version integrity

• Course versions support Draft, In Review, Published, scheduled publish, scheduled unpublish, and safe unpublish states.
• Readiness checks validate metadata, structure, lesson content, Blocks, Assets, assessments, scenarios, and completion rules before review/publish.
• Completion rules use a controlled logical model for required lessons, minimum lesson percentage, assessment pass, minimum score, and required interaction.
• Publishing snapshots taxonomy mappings so later Draft changes never rewrite Published evidence context.
• Published versions remain immutable; forking copies modules, lessons, Blocks, assessments, questions, completion rules, and taxonomy mappings.
• Publishing a new version supports no reassignment or copying all active assignments from its source version.

Assignment engine

• Published Courses and Learning Paths can be assigned to an individual, Team, department, organization, controlled rule, or an uploaded XLSX/CSV audience list.
• Assignments support mandatory status, start/due dates, recurring month interval, reminder days, and manager escalation policy.
• Recipient snapshots preserve assignment history and cancellation state.
• Team and rule audiences are dynamically resolved; newly imported/edited users and newly attached Team members are synchronized automatically.
• Designers can list, create, cancel, filter, and manually resynchronize Assignments from the product UI/API.

Learning Paths

• Learning Paths contain ordered Published Course Versions with optional prerequisites and controlled completion rules.
• The V1 editor is a clean responsive ordered list with visible move controls instead of a complex node canvas.
• Draft paths support add, remove, reorder, metadata, enforced-order setting, review, and publish workflows.
• Published Learning Path Versions are immutable and can be forked without changing prior history.
• Published Learning Paths are available to the Assignment Engine.

Phase 8 quality gates

• Dedicated backend tests cover publish immutability, dynamic Team assignment, and Learning Path version history.
• Full backend suite, frontend typecheck, and production build pass.
• UI follows the existing responsive RTL design system with semantic success/danger states, labelled controls, loading/error/empty states, and confirmation for sensitive actions.

Phase 9 — Learner Player, PWA, and Offline

Learner experience and Player

• Learner navigation provides Home, My Learning, Daily, Progress, and More without exposing a public Course catalog.
• Home uses assigned data for greeting, Continue Learning, Daily Learning, Assigned to You, Due Soon, and verified progress summaries.
• Assignment and tenant authorization protects every Player payload and only exposes referenced private Assets through signed URLs.
• Flow and card/story presentation modes use the same canonical Course Version, Lesson, and Block content.
• Card/story mode remains card-based on desktop and supports vertical touch navigation on mobile.
• Player chrome includes Course, Lesson and overall progress, collapsed outline, previous/next controls, sticky mobile progress, and accessible interaction controls.
• Single Choice, Multiple Choice, True/False, Matching, Sorting, Drag and Drop, Hotspot, Scenario, and Branching Scenario interactions are functional in Player.
• Assessment scores are recalculated from canonical answers on the server and never trusted from the browser payload.
• Completion rules update lesson, course, and Assignment recipient progress from idempotent learning events.

Learner tools and social learning

• Private notes, Block bookmarks, selected-text highlights, and Course favorites persist with learner/tenant scope.
• Lesson discussions support posts, replies, helpful reactions, and scoped authorization.
• Notes can be printed or saved as PDF using a dedicated print layout.
• Notes and saved highlights are visible in one compact Player drawer.

PWA and offline architecture

• Installable web manifest, application icon, theme metadata, and Service Worker registration are present.
• Explicit Course download uses the server manifest and caches only approved referenced Assets.
• IndexedDB stores cached Course payload/download metadata, private notes, progress, and queued learning events.
• Offline events synchronize on reconnect, reconcile local note state, and use client event IDs to prevent duplicate progress and notes.
• Large videos follow an explicit manifest policy and are excluded from automatic offline download above the configured threshold.
• Online, offline, loading, empty, authorization, and recovery states are represented honestly.

Phase 9 quality gates

• Dedicated backend Player tests pass for assignment scope, tenant isolation, event idempotency, completion, private notes/bookmarks, social features, offline notes, and server-side scoring.
• Full backend suite passes: 103 tests and 624 assertions; PHP formatting passes.
• Full frontend suite passes: 12 files and 36 tests; typecheck and zero-warning lint pass.
• Production build and start-dev.bat --check pass.
• Seeded desktop/mobile, light/dark RTL visual review passes for Learner Home and Player; temporary review services are cleaned up.

Phase 10 — Manager Workspace and Learner iOS Experience

Cross-role session controls

• A visible Logout action is available to Designer, Super Admin, Manager, and Learner users.
• Logout shows pending/error feedback, revokes the current API token, clears local authentication state, and returns to Login.
• Learner Player provides a predictable route back to the learner workspace where account and Logout controls remain reachable.
• Automated tests cover Logout visibility and behavior for workspace and learner shells.

Manager authorization and data contracts

• Manager APIs are protected by Manager role/permission checks and derive tenant context only from the authenticated user.
• Every Manager query is restricted to Teams explicitly managed by that Manager; unmanaged and cross-tenant records are not disclosed.
• Manager cannot author, publish, assign, mutate Team membership, or manage organization settings through UI or API.
• Manager Overview returns real, explainable Team Learning Health, completion, engagement, assessment, overdue, at-risk, and attention metrics.
• My Team returns managed Teams and member profiles with assignment/progress summaries and safe drill-down data.
• Learning Status, Courses, Assessments, Attention, Reports, and Notifications use scoped server data with documented empty states.
• No Phase 11 predictive/Monitoring metric is fabricated; unavailable future analytics are labelled honestly.

Manager workspace UI

• /manager provides Overview, My Team, Learning Status, Courses, Assessments, Attention, Reports, and Notifications routes.
• Overview composes reusable metric, health, attention, progress, and status components rather than page-local duplicates.
• Tables/lists support useful Team, status, Course, and due-state filters with responsive card alternatives on mobile.
• Attention items explain why a person needs attention and link to a scoped detail or recommended follow-up.
• Manager pages include loading, empty, error, permission-denied, and retry states.
• Manager workspace is responsive, bilingual, RTL/LTR-safe, keyboard accessible, and uses semantic success/danger colors.

Learner iOS-style redesign

• Learner Home, My Learning, Daily, Progress, More, and Player use one cohesive iOS-inspired visual language in light and dark themes.
• Learner screens use large-title hierarchy, grouped surfaces, restrained blur/elevation, system-like controls, and consistent rounded geometry.
• Bottom navigation is a floating rounded tab bar with five labelled icons, safe-area spacing, visible selected state, and at least 44×44 px touch targets.
• Scroll content reserves enough bottom inset so the floating navigation never covers cards or actions.
• More includes account identity, theme/language access, offline information, and visible Logout.
• Player retains minimal chrome, readable progress, offline state, notes/discussion access, and safe-area-aware controls after the redesign.
• Motion is subtle, interruptible, and disabled/reduced when prefers-reduced-motion is enabled.

Phase 10 quality gates

• Backend tests cover Manager scope, unmanaged/cross-tenant denial, real metric calculations, and forbidden mutations.
• Frontend tests cover Manager routes/states, filters/drill-down, Logout, and learner floating navigation.
• Full backend/frontend tests, typecheck, zero-warning lint, PHP formatting, and production build pass.
• start-dev.bat --check, seeded Manager/Learner smoke tests, and temporary-service cleanup pass.
• Visual review passes for Manager desktop/tablet/mobile and learner iOS-style small-phone/large-phone/desktop in FA/EN, RTL/LTR, light/dark.

Phase 11 — Event Pipeline, Analytics, and Monitoring Engine

Event contracts and processing

• Learning Events use a versioned, allow-listed taxonomy with server-owned tenant and actor context.
• Event ingestion preserves immutable raw facts, client idempotency, occurred/received time, session, correlation, causation, and device context.
• Offline and late events are accepted safely without duplicate projections or client-controlled analytics values.
• Projection processing is idempotent, retryable, observable, and can rebuild derived metrics from raw events.
• Meaningful Course, Lesson, Block, video, assessment, social, note, and completion interactions emit documented events.

Metrics and learning intelligence

• Metrics Engine derives completion, on-time completion, engagement, learning time, inactivity, and progress velocity from canonical data.
• Course/Lesson/Block analytics expose starts, completions, drop-off, and drill-down without fabricated telemetry.
• Video analytics support reliable start, 25/50/75 percent, completion, average watch, exit point, replay, and skip signals.
• Assessment analytics expose score, pass rate, attempts, question difficulty, common wrong answers, and Team comparison.
• Evidence processing remains immutable and triggers versioned Capability score, confidence, snapshot, gap, and coverage recalculation.
• Insufficient evidence is labelled honestly and score precision never exceeds evidence quality.

Monitoring, Risk, Attention, and actions

• Learning Health uses centrally configured weights and exposes every contributing factor.
• V1 Risk Score is an explainable heuristic behind a provider abstraction and is never labelled as ML probability.
• Insight and Attention items contain severity, reason, entity, evidence, trend, suggested action, and drill-down destination.
• Attention supports inactivity, deadline risk, engagement decline, drop-off, assessment difficulty, capability gaps, confidence, and coverage warnings.
• Raw events remain conceptually and physically separate from metrics, insights, risks, and attention projections.

APIs, privacy, and UI

• Designer Monitoring APIs are tenant-scoped; Manager analytics are limited to managed Teams; Super Admin cannot access employee learning analytics.
• Analytics filters support date, Team, Course, learner status, skill/competency, evidence type, and confidence where relevant.
• Drill-down supports Organization → Team → Course → Module → Lesson → Block with stable URLs and a predictable back path.
• Monitoring UI provides Overview, Health, Engagement, Courses, Teams, Learners, Assessments, Skills & Competencies, Risk, and Reports.
• Charts use suitable forms, visible units/legends, keyboard-readable summaries, responsive layouts, and accessible table alternatives.
• Every Monitoring screen includes loading, empty, insufficient-data, error, retry, FA/EN, RTL/LTR, light/dark, and reduced-motion states.

Phase 11 quality gates

• Backend tests cover event schema, idempotency, late events, projection rebuild, metric formulas, risk explanation, privacy, and tenant isolation.
• Frontend tests cover Monitoring routes, filters, chart summaries, drill-down, empty/error states, and role authorization.
• Full backend/frontend tests, PHP formatting, lint, typecheck, migrations, seed, and production build pass.
• start-dev.bat --check, four-role smoke tests, seeded analytics smoke test, and temporary-service cleanup pass.
• Visual review passes for Monitoring desktop/tablet/mobile in FA/EN, RTL/LTR, light/dark, including a 375px viewport.

Phase 12 — Collaboration and Realtime

Cross-role routing and account header corrections

• Login replaces an existing session safely and redirects only to a route compatible with the newly authenticated role.
• Designer, Super Admin, Manager, and Learner can switch accounts without landing in another role's workspace or a permission dead end.
• Direct navigation to an incompatible workspace redirects to the authenticated role home while backend authorization remains authoritative.
• Workspace profile moves from the sidebar to the top bar beside theme and notifications, with accessible account details and Logout.
• Header account controls remain usable at 375px, RTL/LTR, light/dark, keyboard, and reduced-motion settings.

Collaboration domain and authorization

• Multiple Designers can open the same Course Version and see active presence with stale-session expiry.
• Block-level soft locks use renewable leases, prevent conflicting edits, identify the holder, and never become permanent hard locks.
• Collaboration access is tenant-scoped and restricted to authorized Course Designers; published content remains immutable.
• Collaboration mutations are idempotent where retry/offline behavior can duplicate a request.
• The canonical Course/Version/Lesson/Block model remains the single collaboration target; no duplicate editor document is introduced.

Comments, review, mentions, reactions, and notifications

• Block and Course review comments support open/resolved state, threaded replies, @mentions, and reactions.
• Mention targets are restricted to active same-tenant collaborators and cannot disclose cross-tenant identities.
• Review Center aggregates unresolved threads, resolution state, author, target, timestamps, and stable Builder deep-links.
• In-app notifications cover mentions, replies, reactions, review changes, and lock conflicts with read/unread state.
• Notification links route each role to an authorized destination and degrade safely when a target is no longer available.

Realtime transport and UI

• Presence, soft locks, comments, and notifications publish versioned collaboration changes through a transport abstraction.
• UI updates promptly when change delivery is available and falls back to bounded API refresh without losing core functionality.
• Builder shows presence and lock ownership without implying Google Docs-style simultaneous text editing.
• Collaboration panel and Review Center include loading, empty, error, retry, offline/degraded, and permission states.
• Collaboration UI is responsive, bilingual, RTL/LTR-safe, light/dark, keyboard accessible, and uses 44px minimum targets.

Phase 12 quality gates

• Backend tests cover presence expiry, lock acquire/renew/release/conflict, comments, mentions, reactions, notifications, permissions, and tenant isolation.
• Frontend tests cover four-role routing, header profile behavior, collaboration states, lock conflicts, review actions, and refresh fallback.
• Full backend/frontend tests, PHP formatting, lint, typecheck, migrations, seed, and production build pass.
• start-dev.bat --check, four-role account-switch smoke tests, collaboration smoke tests, and temporary-service cleanup pass.
• Visual review passes for account header, Builder collaboration, and Review Center on desktop/tablet/375px in FA/EN, RTL/LTR, light/dark.

Phase 13 — Product Completion, AI Studio, and Document Ingestion

Cross-role product completion

• Designer Dashboard opens the complete Monitoring experience instead of the Foundation placeholder.
• Designer Reports, Export Center, Skills & Competencies, Certificates, Brand Kit, Settings, and Templates are functional screens with real data or honest actionable empty states.
• Admin Dashboard exposes real platform monitoring and Organizations, subscriptions, usage, storage, AI usage, system health, audit, and settings no longer use Foundation placeholders.
• Course Workspace Learners, Analytics, Discussion, and Settings tabs are active, distinct, and explain their purpose without duplicate Settings tabs.
• User directory uses an 11px dense table presentation while preserving readable mobile cards and 44px actions.

Branding and role-aware personalization

• Supplied MicroLearn logo is installed as the application mark, favicon, Apple touch icon, and PWA icons.
• Organization Brand Kit supports logo, display name, primary/accent colors, learner welcome copy, and certificate identity.
• Designer, Admin, Manager, and Learner personalization surfaces expose only role-appropriate preferences.
• Branding and preferences persist with tenant/user scoping and safe defaults across FA/EN and light/dark themes.

Notifications

• Notifications are removed from Designer and Manager side navigation and open from an accessible top-bar popover.
• Learner receives an iOS-style notification sheet from the learner header.
• Manager and Learner notification cards support left/right swipe with visible non-gesture alternatives.
• Notification read/dismiss actions are tenant-scoped, keyboard accessible, reduced-motion-safe, and show honest empty/error states.

AI provider and governance

• AI operations use a provider abstraction with explicit local/external/disabled state and no direct provider coupling in Course code.
• AI operations record organization, actor, provider, operation, status, usage, error, and timing without logging private prompts unnecessarily.
• Organization quota and On-Prem external-AI disablement are enforced server-side.
• Generated content and taxonomy mappings are always Draft proposals requiring Designer confirmation and can never auto-publish.

Document ingestion and provenance

• PDF, DOCX, and PPTX uploads are privately stored, MIME-validated, size-limited, and processed through resumable/idempotent ingestion jobs.
• Extraction normalizes text, identifies sections, proposes Modules/Lessons, and preserves page/slide/source-fragment provenance.
• Existing SCORM is retained as packaged external learning content and is never reverse-engineered into editable Blocks.
• Designers can inspect source versus proposal, edit structure, retry/cancel failures, and accept a proposal into a canonical Draft Course Version.

AI Studio and Builder assistance

• /app/ai-studio shows ingestion/generation jobs, progress, provider state, quota, retry/cancel, and source traceability.
• Create Course offers Blank, Template, Import Content, and Create with AI as four working paths.
• AI course creation accepts topic, audience, objective, duration, difficulty, language, tone, lesson count, assessment level, and interaction density.
• Builder assistant supports Generate Lesson/Quiz, Rewrite, Shorten, Simplify, Examples, Interaction, Split, Audit, Objectives, and Assessment Alignment through preview/diff confirmation.
• AI taxonomy assistance suggests existing same-tenant Skills/Competencies with rationale/confidence and persists only after explicit confirmation.

Phase 13 quality gates

• Backend tests cover authorization, tenant isolation, provider disabled/quota states, ingestion formats, provenance, idempotency, Draft-only acceptance, and taxonomy confirmation.
• Frontend tests cover completed routes, notification popovers/swipe alternatives, Course tabs, personalization, AI Studio states, and proposal confirmation.
• Full backend/frontend tests, migrations, seed, Pint, lint, typecheck, and production build pass.
• Four-role smoke tests and visual review pass on desktop/tablet/375px in FA/EN, RTL/LTR, light/dark, and reduced motion.

Phase 14 — Export Center and Certificates

Export engine

• Central Export Center lists Published Course Versions, formats, queue status, progress, history, size, errors, retry, cancel, and download.
• SCORM 1.2, SCORM 2004, xAPI, cmi5, Standalone HTML5, PDF Workbook, and adapter-based MP4 are represented behind canonical render adapters.
• Compatibility checks run before generation and require explicit confirmation for deterministic static fallbacks.
• Export generation is asynchronous, tenant-scoped, retained according to policy, and stored through the configured filesystem abstraction.
• PDF Workbook includes cover, TOC, modules, lessons, static interaction representations, branding, and page footer/numbering.

Certificates

• Completion-rule satisfaction issues an idempotent certificate automatically and manual issuance is limited to eligible completions.
• Certificates include unique number/code, issue date, optional expiry, branded PDF, QR, verification URL, and immutable issuance snapshot.
• Public /certificate/verify/:code shows only safe verification data and clearly distinguishes valid, expired, revoked, and unknown credentials.
• Certificate Builder supports branded canvas preview, layers, colors, signature identity, default templates, download, and reasoned revocation.
• Certificate issuance creates a learner notification and remains tenant-isolated.

Phase 14 quality gates

• Backend tests cover compatibility, queue jobs, tenant isolation, artifact download, eligibility, idempotent issuance, QR verification, expiry, and revocation.
• Frontend tests cover export states, warning confirmation, certificate builder/issuance, and public verification states.
• Full backend/frontend tests, Pint, lint, typecheck, migration, seed, build, and browser smoke pass.

Phase 15 — Production Hardening, On-Prem, and Deployment

Runtime and security

• Production containers provide Nginx, PHP-FPM, worker, scheduler, MySQL, Redis, and S3-compatible storage with restart and health policies.
• Nginx/PHP enforce 2 GB uploads, safe timeouts, security headers, private storage boundaries, SPA routing, and API proxying.
• Production and On-Prem environment templates keep secrets out of source and expose deployment/storage/queue/mail/AI controls.
• Health checks report API, database, storage, queue, scheduler, mail, WebSocket, export worker, and AI adapter status without exposing credentials.
• On-Prem capability mode hides SaaS-only controls and defaults external AI off while supporting local or S3-compatible storage.

Operations and release

• Backup and restore scripts cover MySQL and private storage with explicit verification and migration steps.
• Upgrade, rollback, backup/restore, incident, queue, scheduler, storage, and certificate/export runbooks are documented.
• CI runs dependency audit, formatting, backend/frontend tests, lint, typecheck, migrations, and production build.
• Deployment documentation includes prerequisites, TLS boundary, first boot, migrations, workers, scheduler, health, scaling, observability, and disaster recovery.
• Final live smoke verifies launcher, four roles, core APIs, Export/Certificate flows, and clean runtime logs.

Phase 15 quality gates

• Docker Compose configuration validation and production image builds are enforced in CI; local Docker was unavailable for a duplicate build.
• SaaS and On-Prem capability tests, production config checks, dependency audits, and full automated suites pass.
• No implemented-scope placeholder remains; final checklist and handoff documentation are complete.