From 64da4531520b8df236ad3bd98b066725610ec149 Mon Sep 17 00:00:00 2001
From: n8n IEC 62304 Bot <n8n-iec62304-bot@local>
Date: Mon, 6 Jul 2026 21:15:15 +0200
Subject: [PATCH] docs(iec62304): [REL-1.0.2] validate and curate XML doc
 review markers

---
 .../Repositories/MasterListRepository.cs      | 70 +++++++++++++++++++
 adas-core.LdapLogin/LdapLoginService.cs       | 19 +++++
 2 files changed, 89 insertions(+)

diff --git a/adas-core.Infrastructure/Repositories/MasterListRepository.cs b/adas-core.Infrastructure/Repositories/MasterListRepository.cs
index a16f76be..9b4745ef 100644
--- a/adas-core.Infrastructure/Repositories/MasterListRepository.cs
+++ b/adas-core.Infrastructure/Repositories/MasterListRepository.cs
@@ -20,6 +20,7 @@ namespace adas_core.Infrastructure.Repositories;
 /// options lists, diagnoses, allergies, procedures, treatments, and other reference data.
 /// </summary>
 /// <typeparam name="T">The type of MasterList entity to manage.</typeparam>
+/// <!-- aidoc:v1 sig=f958de2 -->
 public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository<T> where T : MasterList
 {
     private readonly ApiSettings _apiSettings;
@@ -30,6 +31,7 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
     /// <param name="apiSettings">API settings containing collection names configuration.</param>
     /// <param name="database">The MongoDB database instance.</param>
     /// <exception cref="ArgumentNullException">Thrown when apiSettings is null.</exception>
+    /// <!-- aidoc:v1 sig=800d538 body=d2b18a3 -->
     public MasterListRepository(IOptions<ApiSettings> apiSettings, IMongoDatabase database) : base(database)
     {
         if (apiSettings == null) throw new ArgumentNullException(nameof(apiSettings));
@@ -41,6 +43,7 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
     /// Maps different MasterList subtypes to their corresponding MongoDB collection names.
     /// </summary>
     /// <returns>The collection name for the current MasterList type.</returns>
+    /// <!-- aidoc:v1 sig=94e22ff body=64e6c55 -->
     public override string GetCollectionName()
     {
         return typeof(T) switch
@@ -94,6 +97,7 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
     /// </summary>
     /// <param name="id">The ObjectId of the entity to delete.</param>
     /// <exception cref="Exception">Throws and re-throws exceptions after logging.</exception>
+    /// <!-- aidoc:v1 sig=3de1ad6 body=fe0ba8c -->
     public async Task Delete(ObjectId id)
     {
         try
@@ -113,6 +117,8 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
     /// </summary>
     /// <param name="entity">The entity with updated values.</param>
     /// <exception cref="Exception">Throws and re-throws exceptions after logging.</exception>
+    /// <!-- aidoc-review:v1 severity=low kind=wrong_summary
+    ///      "Summary says 'Updates an existing' entity, but ReplaceOptions { IsUpsert = true } allows the operation to also insert a new entity if none matches the filter, so 'existing' is not strictly accurate." -->
     public async Task Update(T entity)
     {
         try
@@ -133,6 +139,7 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
     /// <param name="id">The ObjectId of the master list.</param>
     /// <param name="newOpt">The OptionList with updated values.</param>
     /// <returns>The updated OptionList if found; otherwise, null.</returns>
+    /// <!-- aidoc:v1 sig=64ca4dd body=a7714e6 -->
     public async Task<OptionList?> UpdateFullMasterListOption(ObjectId id, OptionList newOpt)
     {
         var filter = Builders<T>.Filter.Where(o => o.Id == id && o.Options.Any(opt => opt.Id == newOpt.Id)
@@ -166,6 +173,12 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
     /// <param name="id">The ObjectId of the entity to retrieve.</param>
     /// <returns>The MasterList entity if found; otherwise, null.</returns>
     /// <exception cref="Exception">Logs errors and returns null on failure.</exception>
+    /// <!-- aidoc-review:v1 severity=high kind=wrong_summary
+    ///      "Method is generic on T, not specific to 'master list' entities" -->
+    /// <!-- aidoc-review:v1 severity=high kind=wrong_returns
+    ///      "Returns T? (generic), not specifically a 'MasterList entity'" -->
+    /// <!-- aidoc-review:v1 severity=high kind=extra_exception
+    ///      "<exception cref='Exception'> is misleading: the catch block swallows all exceptions and returns null; the method does not propagate an Exception to callers" -->
     public async Task<T?> FindById(ObjectId id)
     {
         try
@@ -197,6 +210,8 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
     /// <param name="locale">The locale for translation.</param>
     /// <returns>The OptionList with translated fields if found; otherwise, null.</returns>
     /// <exception cref="Exception">Logs errors and returns null on failure.</exception>
+    /// <!-- aidoc-review:v1 severity=medium kind=extra_exception
+    ///      "The method's try/catch catches all Exception instances and returns null, so it does not propagate any exception to the caller; the <exception cref=\"Exception\"/> tag is therefore misleading." -->
     public async Task<OptionList?> FindOptionItemById(ObjectId masterId, ObjectId optionId, LocaleEnum locale)
     {
         try
@@ -342,6 +357,7 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
     /// <param name="optionId">The ObjectId of the option to retrieve.</param>
     /// <returns>The OptionList if found; otherwise, null.</returns>
     /// <exception cref="Exception">Logs errors and returns null on failure.</exception>
+    /// <!-- aidoc:v1 sig=ccc34cb body=71837cc -->
     public async Task<OptionList?> FindOptionItemById(ObjectId masterId, ObjectId optionId)
     {
         try
@@ -374,6 +390,10 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
     /// <param name="locale">Optional locale for translated option names.</param>
     /// <returns>The MasterList entity with translated options if found; otherwise, null.</returns>
     /// <exception cref="Exception">Logs errors and returns null on failure.</exception>
+    /// <!-- aidoc-review:v1 severity=medium kind=wrong_exception
+    ///      "Method catches all exceptions and returns null; it never throws Exception, so the <exception cref=\"Exception\"/> tag is misleading." -->
+    /// <!-- aidoc-review:v1 severity=medium kind=wrong_returns
+    ///      "Returns is documented as 'MasterList entity' but the method signature is generic Task<T?> and does not indicate T is MasterList." -->
     public async Task<T?> FindById(ObjectId id, LocaleEnum? locale)
     {
         try
@@ -556,6 +576,12 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
     /// <param name="name">The name of the master list to retrieve.</param>
     /// <returns>The MasterList entity if found; otherwise, null.</returns>
     /// <exception cref="Exception">Logs errors and returns null on failure.</exception>
+    /// <!-- aidoc-review:v1 severity=high kind=wrong_summary
+    ///      "Method is generic on T, not specific to a 'master list entity'." -->
+    /// <!-- aidoc-review:v1 severity=high kind=wrong_returns
+    ///      "Documents return of 'The MasterList entity', but the method returns generic Task<T?>, not a concrete MasterList type." -->
+    /// <!-- aidoc-review:v1 severity=high kind=wrong_exception
+    ///      "Documents <exception cref='Exception'>, but the method catches all exceptions internally and never propagates one to the caller." -->
     public async Task<T?> FindByName(string name)
     {
         try
@@ -584,6 +610,7 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
     /// <param name="id">The ObjectId of the master list.</param>
     /// <param name="textSearch">Optional text to search within options.</param>
     /// <returns>A list of matching OptionList items.</returns>
+    /// <!-- aidoc:v1 sig=569d223 body=bb7f2c6 -->
     public async Task<List<OptionList>> GetMasterListByIdAndTextSearchContaining(ObjectId id, string? textSearch)
     {
         return await GetOptionsByTextSearch(textSearch, id);
@@ -594,6 +621,7 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
     /// </summary>
     /// <param name="filter">The pagination and filtering parameters.</param>
     /// <returns>A fluent queryable for MasterList results.</returns>
+    /// <!-- aidoc:v1 sig=bbb39c7 body=f42ebaa -->
     public IFindFluent<T, T> GetPaginatedMasterList(PaginationFilter filter)
     {
         var filterBuilder = Builders<T>.Filter;
@@ -621,6 +649,10 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
     /// <param name="filter">The pagination and filtering parameters.</param>
     /// <param name="listId">The ObjectId of the master list.</param>
     /// <returns>A list of filtered OptionList items.</returns>
+    /// <!-- aidoc-review:v1 severity=high kind=wrong_summary
+    ///      "Summary states the method retrieves 'paginated options', but the code contains no pagination logic (no Skip/Take, page index, or page size handling). The method only applies an optional text filter and returns all matching options via ToList()." -->
+    /// <!-- aidoc-review:v1 severity=high kind=wrong_param_role
+    ///      "filter is documented as 'The pagination and filtering parameters', but the code only reads filter.FilteredRequest.Text; no pagination fields of the filter are consumed." -->
     public async Task<List<OptionList>> GetPaginatedOptions(PaginationFilter filter, ObjectId listId)
     {
         //TODO: LOCALE
@@ -646,6 +678,8 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
     /// <param name="opt">The option element to add.</param>
     /// <returns>The newly created OptionList if successful; otherwise, null if duplicate exists.</returns>
     /// <exception cref="Exception">Logs errors and returns null on failure.</exception>
+    /// <!-- aidoc-review:v1 severity=high kind=wrong_exception
+    ///      "The method catches all exceptions internally and returns null; it never throws Exception to the caller, so the <exception cref=\"Exception\"> tag is misleading." -->
     public async Task<OptionList?> AddOptionToMasterList(ObjectId id, FilterOptionListElement opt)
     {
         var exist = await GetMasterListByIdAndSearchOptions(id, opt);
@@ -689,6 +723,12 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
     /// </summary>
     /// <returns>An enumerable of all MasterList entities.</returns>
     /// <exception cref="Exception">Logs errors and returns empty list on failure.</exception>
+    /// <!-- aidoc-review:v1 severity=high kind=wrong_summary
+    ///      "Summary references 'master list entities' but the method is generic (IEnumerable<T>) and does not specifically operate on MasterList." -->
+    /// <!-- aidoc-review:v1 severity=high kind=wrong_returns
+    ///      "Returns tag describes 'MasterList entities' but the method returns IEnumerable<T>, a generic type." -->
+    /// <!-- aidoc-review:v1 severity=high kind=wrong_exception
+    ///      "Exception tag documents Exception, but the method catches all exceptions and never re-throws; it returns an empty list on failure instead of throwing." -->
     public async Task<IEnumerable<T>> GetAll()
     {
         try
@@ -708,6 +748,8 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
     /// </summary>
     /// <returns>An enumerable of MasterListDto containing id, name, description, listType, and options count.</returns>
     /// <exception cref="Exception">Logs errors and returns empty list on failure.</exception>
+    /// <!-- aidoc-review:v1 severity=medium kind=extra_exception
+    ///      "The method catches all exceptions, logs them, and returns an empty list; no exception propagates to the caller, so the <exception> tag is misleading" -->
     public async Task<IEnumerable<MasterListDto>> GetAllWithoutOptions()
     {
         try
@@ -736,6 +778,8 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
     /// </summary>
     /// <returns>The total count of entities.</returns>
     /// <exception cref="Exception">Logs errors and returns 0 on failure.</exception>
+    /// <!-- aidoc-review:v1 severity=medium kind=wrong_exception
+    ///      "The method catches all exceptions internally and never throws to the caller, so documenting <exception cref=\"Exception\"> is misleading. The catch block logs and returns 0 instead of propagating the exception." -->
     public async Task<int> Count()
     {
         try
@@ -758,6 +802,10 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
     /// <param name="filters">The filter criteria including text, name, description, and optionType.</param>
     /// <returns>A list of matching OptionList items ordered by name.</returns>
     /// <exception cref="Exception">Logs errors and returns empty list on failure.</exception>
+    /// <!-- aidoc-review:v1 severity=high kind=extra_exception
+    ///      "The method catches all exceptions internally and never propagates one to the caller, so documenting <exception cref=\"Exception\"> is misleading; the method always returns a list (possibly empty)." -->
+    /// <!-- aidoc-review:v1 severity=high kind=missing_param
+    ///      "The filters parameter also contains a 'Locale' property used to drive translation selection, which is not mentioned in the <param> description." -->
     public async Task<List<OptionList>> GetMasterListByIdAndSearchOptions(ObjectId id, FilterOptionListElement? filters)
     {
         try
@@ -973,6 +1021,8 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
     /// <param name="locale">The locale for translation updates.</param>
     /// <returns>The updated OptionList if successful; otherwise, null.</returns>
     /// <exception cref="Exception">Logs errors and returns null on failure.</exception>
+    /// <!-- aidoc-review:v1 severity=medium kind=extra_exception
+    ///      "The method catches all exceptions internally and never throws to the caller, so the <exception> tag is misleading; the catch block logs and returns null, but no exception propagates." -->
     public async Task<OptionList?> UpdateMasterListOption(ObjectId id, OptionList newOpt, LocaleEnum locale)
     {
         // 1. Evitar duplicados
@@ -1073,6 +1123,8 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
     /// <param name="newOpt">The OptionList with updated values.</param>
     /// <returns>The updated OptionList if successful; otherwise, null.</returns>
     /// <exception cref="Exception">Logs errors and returns null on failure.</exception>
+    /// <!-- aidoc-review:v1 severity=high kind=wrong_exception
+    ///      "The <exception cref=\"Exception\"> tag implies the method throws Exception to the caller, but the code catches all exceptions internally and returns null instead of throwing." -->
     public async Task<OptionList?> UpdateMasterListOption(ObjectId id, OptionList newOpt)
     {
         var master = await FindById(id);
@@ -1108,6 +1160,7 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
     /// <param name="id">The ObjectId of the master list.</param>
     /// <param name="deleteOptId">The ObjectId of the option to delete.</param>
     /// <returns>True if the option was deleted; otherwise, false.</returns>
+    /// <!-- aidoc:v1 sig=e663f16 body=75627bc -->
     public async Task<bool> DeleteMasterListOption(ObjectId id, ObjectId deleteOptId)
     {
         // Define el filtro para encontrar el documento por su _id
@@ -1132,6 +1185,8 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
     /// <param name="opt">The UpdateMasterListDetailsDto with updated values.</param>
     /// <returns>The updated UpdateMasterListDetailsDto if successful; otherwise, null.</returns>
     /// <exception cref="Exception">Logs errors and returns null on failure.</exception>
+    /// <!-- aidoc-review:v1 severity=high kind=wrong_exception
+    ///      "The <exception cref=\"Exception\"> tag is incorrect: the method catches all exceptions in a try/catch and returns null, rather than throwing Exception. The detail text 'Logs errors and returns null on failure' describes the catch block, not a thrown exception." -->
     public async Task<UpdateMasterListDetailsDto?> UpdateOptionDetailsToMasterList(ObjectId id,
         UpdateMasterListDetailsDto opt)
     {
@@ -1167,6 +1222,8 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
     /// <param name="name">The new name.</param>
     /// <returns>True if the update was successful; otherwise, false.</returns>
     /// <exception cref="Exception">Logs errors and returns false on failure.</exception>
+    /// <!-- aidoc-review:v1 severity=medium kind=wrong_exception
+    ///      "The method catches all exceptions in its try/catch block and returns false; it never propagates an Exception to callers, so the <exception cref=\"Exception\"> tag is misleading." -->
     public async Task<bool> UpdateMasterListName(ObjectId id, string name)
     {
         var filter = Builders<T>.Filter.And(
@@ -1193,6 +1250,8 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
     /// <param name="description">The new description.</param>
     /// <returns>True if the update was successful; otherwise, false.</returns>
     /// <exception cref="Exception">Logs errors and returns false on failure.</exception>
+    /// <!-- aidoc-review:v1 severity=high kind=wrong_exception
+    ///      "The <exception cref=\"Exception\"> tag is misused. The method catches all exceptions internally and returns false, so no exception ever propagates to the caller. The tag incorrectly implies the method may throw an exception to its caller." -->
     public async Task<bool> UpdateMasterListDescription(ObjectId id, string description)
     {
         var filter = Builders<T>.Filter.And(
@@ -1219,6 +1278,7 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
     /// <param name="oldOpt">The OptionList to remove.</param>
     /// <returns>True if the option was removed; otherwise, false.</returns>
     /// <exception cref="Exception">Logs errors and returns false on failure.</exception>
+    /// <!-- aidoc:v1 sig=8de50cd body=d974b9b -->
     public async Task<bool> RemoveMasterListOption(ObjectId id, OptionList oldOpt)
     {
         var filter = Builders<T>.Filter.Eq("_id", id);
@@ -1250,6 +1310,8 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
     /// Creates necessary indexes for the MasterList collection.
     /// Currently creates text indexes for DiagnosisList on options.name, options.description, and options._id.
     /// </summary>
+    /// <!-- aidoc-review:v1 severity=high kind=wrong_summary
+    ///      "Documentation states the method creates 'text indexes' but the code uses Builders<T>.IndexKeys.Ascending(...), which creates single-field ascending indexes, not text indexes." -->
     public override async Task CreateIndexes()
     {
         if (typeof(T) == typeof(DiagnosisList))
@@ -1275,6 +1337,7 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
     /// </summary>
     /// <param name="textSearch">Optional text to search within options.</param>
     /// <returns>A list of matching OptionList items.</returns>
+    /// <!-- aidoc:v1 sig=484b092 body=48e3496 -->
     public async Task<List<OptionList>> GetMasterListByTextSearch(string? textSearch)
     {
         return await GetOptionsByTextSearch(textSearch);
@@ -1287,6 +1350,7 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
     /// <param name="id">Optional master list ObjectId to filter results.</param>
     /// <returns>A list of matching OptionList items ordered by name.</returns>
     /// <exception cref="Exception">Logs errors and returns empty list on failure.</exception>
+    /// <!-- aidoc:v1 sig=6ebeac8 body=1d7bbb7 -->
     private async Task<List<OptionList>> GetOptionsByTextSearch(string? textSearch, ObjectId? id = null)
     {
         try
@@ -1364,6 +1428,8 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
     /// <param name="filters">List of filter definitions to apply.</param>
     /// <param name="sort">Sort definition for the query results.</param>
     /// <returns>A fluent queryable for T results.</returns>
+    /// <!-- aidoc-review:v1 severity=high kind=wrong_summary
+    ///      "Summary claims 'paginated results' but the method does not perform pagination; it only builds a find query with combined filters and a sort, with no Skip or Limit calls." -->
     private IFindFluent<T, T> CreateFindFluent(List<FilterDefinition<T>> filters, SortDefinition<T> sort)
     {
         var combinedFilter = filters.Any()
@@ -1379,6 +1445,7 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
     /// <param name="localeList">The default locale to exclude from translations.</param>
     /// <param name="opt">The option name to use as default translation.</param>
     /// <returns>A Locale object with translations for all other locales.</returns>
+    /// <!-- aidoc:v1 sig=147db59 body=9b63847 -->
     private Locale GetNewItemLocale(LocaleEnum localeList, string opt)
     {
         var newLocale = new Locale();
@@ -1418,6 +1485,7 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
     /// </summary>
     /// <param name="input">The input string to build the pattern from.</param>
     /// <returns>A regex-compatible pattern string.</returns>
+    /// <!-- aidoc:v1 sig=2992c00 body=ae88daf -->
     private static string BuildRegexPattern(string input)
     {
         var regexPattern = new StringBuilder();
@@ -1459,6 +1527,8 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
     /// <param name="locale">The locale for translation.</param>
     /// <returns>A list of matching OptionList items ordered by name.</returns>
     /// <exception cref="Exception">Logs errors and returns empty list on failure.</exception>
+    /// <!-- aidoc-review:v1 severity=medium kind=extra_exception
+    ///      "The method wraps all logic in a try/catch that catches Exception and returns an empty list; no exception is propagated out of the method, so the <exception cref=\"Exception\"> tag is incorrect." -->
     private async Task<List<OptionList>> GetMasterListByIdAndTextSearch(
         ObjectId id, string newOptName, LocaleEnum locale)
     {
diff --git a/adas-core.LdapLogin/LdapLoginService.cs b/adas-core.LdapLogin/LdapLoginService.cs
index c4f63619..b35d2b3c 100644
--- a/adas-core.LdapLogin/LdapLoginService.cs
+++ b/adas-core.LdapLogin/LdapLoginService.cs
@@ -20,6 +20,7 @@ namespace adas_core.LdapLogin;
 /// The service also handles the creation of new users in the application if they do not already exist, based on the LDAP information. 
 /// It uses configuration settings for connecting to the LDAP server and for mapping LDAP attributes to user properties and authorities.
 /// </summary>
+/// <!-- aidoc:v1 sig=4e5637f -->
 public class LdapLoginService : ILoginService
 {
     /// <summary>
@@ -51,6 +52,7 @@ public class LdapLoginService : ILoginService
     /// <param name="userService">The user service for managing user information.</param>
     /// <param name="authorityService">The authority service for managing user authorities.</param>
     /// <param name="logger">The logger for logging LDAP login operations.</param>
+    /// <!-- aidoc:v1 sig=f1b8e4e body=6c4718f -->
     public LdapLoginService(
         IOptions<LdapConfig> ldapConfig,
         IValidator<LdapConfig> validator,
@@ -83,6 +85,7 @@ public class LdapLoginService : ILoginService
     /// <returns>The authenticated user.</returns>
     /// <exception cref="LoginServicesException">Thrown when there is an error during the login process.</exception>
     /// <exception cref="UserNotFoundException">Thrown when the user is not found in the LDAP directory.</exception>
+    /// <!-- aidoc:v1 sig=bdfb451 body=e3fc1ac -->
     public async Task<User> Login(string username, string password)
     {
         if (_ldapConfig.Server == null)
@@ -159,6 +162,7 @@ public class LdapLoginService : ILoginService
     /// <param name="context">The HTTP context of the request.</param>
     /// <returns>A task representing the asynchronous operation.</returns>
     /// <exception cref="LoginServicesException">Thrown when the method is not implemented.</exception>
+    /// <!-- aidoc:v1 sig=851dc90 -->
     public Task<User> Login(HttpContext context)
         => throw new LoginServicesException("Not implemented");
 
@@ -169,6 +173,7 @@ public class LdapLoginService : ILoginService
     /// <param name="password">The password of the user to authenticate.</param>
     /// <returns>A task representing the asynchronous operation.</returns>
     /// <exception cref="LoginServicesException">Thrown when the method is not implemented.</exception>
+    /// <!-- aidoc:v1 sig=a0b1f46 -->
     public Task<User> Authenticate(string username, string password)
         => throw new LoginServicesException("Not implemented");
 
@@ -178,6 +183,7 @@ public class LdapLoginService : ILoginService
     /// <param name="id">The ID of the user to retrieve.</param>
     /// <returns>A task representing the asynchronous operation.</returns>
     /// <exception cref="LoginServicesException">Thrown when the method is not implemented.</exception>
+    /// <!-- aidoc:v1 sig=877a869 -->
     public Task<User?> GetById(ObjectId id)
         => throw new LoginServicesException("Not implemented");
 
@@ -187,6 +193,7 @@ public class LdapLoginService : ILoginService
     /// <param name="email">The email of the user to retrieve.</param>
     /// <returns>A task representing the asynchronous operation.</returns>
     /// <exception cref="LoginServicesException">Thrown when the method is not implemented.</exception>
+    /// <!-- aidoc:v1 sig=ba92b09 -->
     public Task<User?> GetByEmail(string email)
         => throw new LoginServicesException("Not implemented");
 
@@ -196,6 +203,8 @@ public class LdapLoginService : ILoginService
     /// <param name="username">The username of the user to retrieve.</param>
     /// <returns>A task representing the asynchronous operation.</returns>
     /// <exception cref="LoginServicesException">Thrown when the method is not implemented.</exception>
+    /// <!-- aidoc-review:v1 severity=medium kind=missing_returns
+    ///      "The <returns> tag describes a generic 'task representing the asynchronous operation' but does not mention that the task resolves to a User? (nullable User) as per the method signature." -->
     public Task<User?> GetByUsername(string username)
         => throw new LoginServicesException("Not implemented");
 
@@ -204,6 +213,8 @@ public class LdapLoginService : ILoginService
     /// </summary>
     /// <returns>A task representing the asynchronous operation.</returns>
     /// <exception cref="LoginServicesException">Thrown when the method is not implemented.</exception>
+    /// <!-- aidoc-review:v1 severity=low kind=wrong_returns
+    ///      "The <returns> tag says 'A task representing the asynchronous operation' but does not mention the Task<List<User>> return type, omitting the List<User> payload." -->
     public Task<List<User>> GetAllUsers()
         => throw new LoginServicesException("Not implemented");
 
@@ -215,6 +226,7 @@ public class LdapLoginService : ILoginService
     /// <param name="userEntryLdap">The user information obtained from the LDAP entry.</param>
     /// <param name="entry">The LDAP entry containing the user's information.</param>
     /// <returns>The existing or newly created user with updated authorities.</returns>
+    /// <!-- aidoc:v1 sig=87de1c2 body=a43bebd -->
     private async Task<User?> GetOrCreateUser(User userEntryLdap, LdapEntry entry)
 
     {
@@ -239,6 +251,7 @@ public class LdapLoginService : ILoginService
     /// <param name="user">The user whose authorities are being checked.</param>
     /// <param name="entry">The LDAP entry containing the user's information.</param>
     /// <returns>A list of updated authorities for the user.</returns>
+    /// <!-- aidoc:v1 sig=d2bafd5 body=4af15eb -->
     private async Task<List<Authorization>> CheckAuthorities(User user, LdapEntry entry)
 
     {
@@ -289,6 +302,7 @@ public class LdapLoginService : ILoginService
     /// <param name="entry">The LDAP entry containing the user's information.</param>
     /// <param name="user">The user whose authorities are being retrieved.</param>
     /// <returns>A list of authorities for the user based on the whitelist.</returns>
+    /// <!-- aidoc:v1 sig=a8263f0 body=9e6cc38 -->
     private List<Authorization> GetAuthoritiesWhiteList(LdapEntry entry, User user)
 
     {
@@ -331,6 +345,10 @@ public class LdapLoginService : ILoginService
     /// </summary>
     /// <param name="ldapEntry">The LDAP entry containing the user's information.</param>
     /// <returns>The existing or newly created user with updated authorities.</returns>
+    /// <!-- aidoc-review:v1 severity=high kind=wrong_summary
+    ///      "The summary states the method retrieves a list of authorities based on LDAP groups, but the code only constructs a User with UserName and Name (first/last) from LDAP attributes—no authorities are involved." -->
+    /// <!-- aidoc-review:v1 severity=high kind=wrong_returns
+    ///      "The <returns> describes 'The existing or newly created user with updated authorities,' but the method only ever returns a newly constructed User with name properties populated; no authorities are set or updated." -->
     private User GetUser(LdapEntry ldapEntry)
 
     {
@@ -365,6 +383,7 @@ public class LdapLoginService : ILoginService
     /// <param name="ldapEntry">The LDAP entry containing the user's information.</param>
     /// <param name="user">The user whose authorities are being retrieved.</param>
     /// <returns>A list of authorities for the user based on the LDAP entry and the application's configuration.</returns>
+    /// <!-- aidoc:v1 sig=1e1f0f2 body=18015c0 -->
     private List<Authorization> GetAuthoritiesMap(LdapEntry ldapEntry, User user)
 
     {