chore(semantics): checkpoint orphan-reduction hub normalization batch

backend/src/services/git_service.py

@@ -4,12 +4,11 @@
 # @SEMANTICS: git, service, gitpython, repository, version_control
 # @PURPOSE:   Core Git logic using GitPython to manage dashboard repositories.
 # @LAYER:     Service
-# @RELATION:  INHERITS_FROM -> None
-# @RELATION:  USED_BY -> src.api.routes.git
-# @RELATION:  USED_BY -> src.plugins.git_plugin
-# @RELATION:  DEPENDS_ON -> src.core.database.SessionLocal
-# @RELATION:  DEPENDS_ON -> src.models.config.AppConfigRecord
-# @RELATION:  DEPENDS_ON -> src.models.git.GitRepository
+# @RELATION:  USED_BY -> backend.src.api.routes.git
+# @RELATION:  USED_BY -> backend.src.plugins.git_plugin
+# @RELATION:  DEPENDS_ON -> backend.src.core.database.SessionLocal
+# @RELATION:  DEPENDS_ON -> backend.src.models.config.AppConfigRecord
+# @RELATION:  DEPENDS_ON -> backend.src.models.git.GitRepository
 #
 # @INVARIANT: All Git operations must be performed on a valid local directory.
 
@@ -32,14 +31,15 @@ from src.models.git import GitRepository, GitServerConfig
 from src.models.config import AppConfigRecord
 from src.core.database import SessionLocal
 
-# [DEF:GitService:Class]
+# [DEF:backend.src.services.git_service.GitService:Class]
+# @TIER: STANDARD
 # @PURPOSE: Wrapper for GitPython operations with semantic logging and error handling.
 class GitService:
     """
     Wrapper for GitPython operations.
     """
 
-    # [DEF:__init__:Function]
+    # [DEF:backend.src.services.git_service.GitService.__init__:Function]
     # @PURPOSE: Initializes the GitService with a base path for repositories.
     # @PARAM: base_path (str) - Root directory for all Git clones.
     # @PRE: base_path is a valid string path.
@@ -64,7 +64,7 @@ class GitService:
         base.mkdir(parents=True, exist_ok=True)
     # [/DEF:_ensure_base_path_exists:Function]
 
-    # [DEF:_resolve_base_path:Function]
+    # [DEF:backend.src.services.git_service.GitService._resolve_base_path:Function]
     # @PURPOSE: Resolve base repository directory from explicit argument or global storage settings.
     # @PRE: base_path is a string path.
     # @POST: Returns absolute path for Git repositories root.
@@ -254,7 +254,7 @@ class GitService:
                 )
     # [/DEF:_ensure_gitflow_branches:Function]
 
-    # [DEF:_get_repo_path:Function]
+    # [DEF:backend.src.services.git_service.GitService._get_repo_path:Function]
     # @PURPOSE: Resolves the local filesystem path for a dashboard's repository.
     # @PARAM: dashboard_id (int)
     # @PARAM: repo_key (Optional[str]) - Slug-like key used when DB local_path is absent.
@@ -394,7 +394,7 @@ class GitService:
                 session.close()
     # [/DEF:delete_repo:Function]
 
-    # [DEF:get_repo:Function]
+    # [DEF:backend.src.services.git_service.GitService.get_repo:Function]
     # @PURPOSE: Get Repo object for a dashboard.
     # @PRE: Repository must exist on disk for the given dashboard_id.
     # @POST: Returns a GitPython Repo instance for the dashboard.
@@ -1112,7 +1112,7 @@ class GitService:
                 raise HTTPException(status_code=500, detail=f"Git pull failed: {str(e)}")
     # [/DEF:pull_changes:Function]
 
-    # [DEF:get_status:Function]
+    # [DEF:backend.src.services.git_service.GitService.get_status:Function]
     # @PURPOSE: Get current repository status (dirty files, untracked, etc.)
     # @PRE: Repository for dashboard_id exists.
     # @POST: Returns a dictionary representing the Git status.
@@ -1657,7 +1657,7 @@ class GitService:
         }
     # [/DEF:_parse_remote_repo_identity:Function]
 
-    # [DEF:_derive_server_url_from_remote:Function]
+    # [DEF:backend.src.services.git_service.GitService._derive_server_url_from_remote:Function]
     # @PURPOSE: Build API base URL from remote repository URL without credentials.
     # @PRE: remote_url may be any git URL.
     # @POST: Returns normalized http(s) base URL or None when derivation is impossible.
@@ -1744,7 +1744,7 @@ class GitService:
             }
     # [/DEF:promote_direct_merge:Function]
 
-    # [DEF:create_gitea_pull_request:Function]
+    # [DEF:backend.src.services.git_service.GitService.create_gitea_pull_request:Function]
     # @PURPOSE: Create pull request in Gitea.
     # @PRE: Config and remote URL are valid.
     # @POST: Returns normalized PR metadata.
@@ -1832,7 +1832,7 @@ class GitService:
         }
     # [/DEF:create_gitea_pull_request:Function]
 
-    # [DEF:create_github_pull_request:Function]
+    # [DEF:backend.src.services.git_service.GitService.create_github_pull_request:Function]
     # @PURPOSE: Create pull request in GitHub or GitHub Enterprise.
     # @PRE: Config and remote URL are valid.
     # @POST: Returns normalized PR metadata.
@@ -1886,7 +1886,7 @@ class GitService:
         }
     # [/DEF:create_github_pull_request:Function]
 
-    # [DEF:create_gitlab_merge_request:Function]
+    # [DEF:backend.src.services.git_service.GitService.create_gitlab_merge_request:Function]
     # @PURPOSE: Create merge request in GitLab.
     # @PRE: Config and remote URL are valid.
     # @POST: Returns normalized MR metadata.

backend/src/services/resource_service.py

@@ -3,9 +3,10 @@
 # @SEMANTICS: service, resources, dashboards, datasets, tasks, git
 # @PURPOSE:   Shared service for fetching resource data with Git status and task status
 # @LAYER:     Service
-# @RELATION:  DEPENDS_ON -> backend.src.core.superset_client
-# @RELATION:  DEPENDS_ON -> backend.src.core.task_manager
-# @RELATION:  DEPENDS_ON -> backend.src.services.git_service
+# @RELATION:  DEPENDS_ON ->[backend.src.core.superset_client.SupersetClient]
+# @RELATION:  DEPENDS_ON ->[TaskManagerPackage]
+# @RELATION:  DEPENDS_ON ->[TaskManagerModels]
+# @RELATION:  DEPENDS_ON ->[backend.src.services.git_service.GitService]
 # @INVARIANT: All resources include metadata about their current state
 
 # [SECTION: IMPORTS]
@@ -17,12 +18,12 @@ from ..services.git_service import GitService
 from ..core.logger import logger, belief_scope
 # [/SECTION]
 
-# [DEF:ResourceService:Class]
+# [DEF:backend.src.services.resource_service.ResourceService:Class]
 # @TIER: STANDARD
 # @PURPOSE: Provides centralized access to resource data with enhanced metadata
 class ResourceService:
     
-    # [DEF:__init__:Function]
+    # [DEF:backend.src.services.resource_service.ResourceService.__init__:Function]
     # @TIER: TRIVIAL
     # @PURPOSE: Initialize the resource service with dependencies
     # @PRE: None
@@ -31,9 +32,9 @@ class ResourceService:
         with belief_scope("ResourceService.__init__"):
             self.git_service = GitService()
             logger.info("[ResourceService][Action] Initialized ResourceService")
-    # [/DEF:__init__:Function]
+    # [/DEF:backend.src.services.resource_service.ResourceService.__init__:Function]
     
-    # [DEF:get_dashboards_with_status:Function]
+    # [DEF:backend.src.services.resource_service.ResourceService.get_dashboards_with_status:Function]
     # @TIER: STANDARD
     # @PURPOSE: Fetch dashboards from environment with Git status and last task status
     # @PRE: env is a valid Environment object
@@ -41,9 +42,9 @@ class ResourceService:
     # @PARAM: env (Environment) - The environment to fetch from
     # @PARAM: tasks (List[Task]) - List of tasks to check for status
     # @RETURN: List[Dict] - Dashboards with git_status and last_task fields
-    # @RELATION: CALLS ->[SupersetClient:get_dashboards_summary]
-    # @RELATION: CALLS ->[self:_get_git_status_for_dashboard]
-    # @RELATION: CALLS ->[self:_get_last_llm_task_for_dashboard]
+    # @RELATION: CALLS ->[backend.src.core.superset_client.SupersetClient.get_dashboards_summary]
+    # @RELATION: CALLS ->[backend.src.services.resource_service.ResourceService._get_git_status_for_dashboard]
+    # @RELATION: CALLS ->[backend.src.services.resource_service.ResourceService._get_last_llm_task_for_dashboard]
     async def get_dashboards_with_status(
         self, 
         env: Any,