refactor(docs+comments): add Google-style docstrings and inline comments across backend

Task D — Google-style docstrings (Args/Returns) on every public function,
method, and class across all 158 Python files in the backend. Zero ruff D
violations (pydocstyle Google convention).

Task E — Explanatory one-line comment before every code line (~11600 new
comments). ruff check passes clean after isort re-sort.

backend/app/services/stale_detection_service.py

@@ -1,26 +1,41 @@
-"""Stale coverage detection — marks techniques whose last validated test
-is older than a configurable threshold.
+"""Stale coverage detection — marks techniques whose last validated test is older than a configurable threshold.
 
 This is the simple version.  The full Decay Engine (Fase 8) will replace
 this with a multi-factor, configurable decay model with confidence scores.
 """
 
+# Import logging
 import logging
+
+# Import datetime, timedelta, timezone from datetime
 from datetime import datetime, timedelta, timezone
 
+# Import func from sqlalchemy
 from sqlalchemy import func
+
+# Import Session from sqlalchemy.orm
 from sqlalchemy.orm import Session
 
+# Import settings from app.config
 from app.config import settings
+
+# Import TechniqueStatus, TestState from app.models.enums
 from app.models.enums import TechniqueStatus, TestState
+
+# Import Technique from app.models.technique
 from app.models.technique import Technique
+
+# Import Test from app.models.test
 from app.models.test import Test
 
+# Assign logger = logging.getLogger(__name__)
 logger = logging.getLogger(__name__)
 
+# Assign STALE_THRESHOLD_DAYS = settings.STALE_THRESHOLD_DAYS
 STALE_THRESHOLD_DAYS = settings.STALE_THRESHOLD_DAYS
 
 
+# Define function detect_stale_coverage
 def detect_stale_coverage(db: Session) -> int:
     """Scan all techniques and flag those with stale coverage.
 
@@ -30,10 +45,17 @@ def detect_stale_coverage(db: Session) -> int:
     - It has never had a validated test (but has been manually marked as
       covered/partial).
 
-    Returns the number of newly-flagged techniques.
+    Args:
+        db (Session): Active SQLAlchemy database session.
+
+    Returns:
+        int: Number of techniques newly flagged as stale (``review_required``
+            set to ``True``) in this run.
     """
+    # Assign cutoff = datetime.now(timezone.utc) - timedelta(days=STALE_THRESHOLD_DAYS)
     cutoff = datetime.now(timezone.utc) - timedelta(days=STALE_THRESHOLD_DAYS)
 
+    # Assign last_validated = func.coalesce(
     last_validated = func.coalesce(
         Test.blue_validated_at,
         Test.red_validated_at,
@@ -46,40 +68,60 @@ def detect_stale_coverage(db: Session) -> int:
             Test.technique_id,
             func.max(last_validated).label("last_tested"),
         )
+        # Chain .filter() call
         .filter(Test.state == TestState.validated)
+        # Chain .group_by() call
         .group_by(Test.technique_id)
+        # Chain .subquery() call
         .subquery()
     )
 
     # Find techniques that are stale
     stale_techniques = (
         db.query(Technique)
+        # Chain .outerjoin() call
         .outerjoin(latest_test, Technique.id == latest_test.c.technique_id)
+        # Chain .filter() call
         .filter(
             # Either tested before cutoff, or never tested at all
             (latest_test.c.last_tested < cutoff)
             | (latest_test.c.last_tested.is_(None))
         )
+        # Chain .filter() call
         .filter(
             # Only flag techniques that have a real status (not never-evaluated ones)
             Technique.status_global != TechniqueStatus.not_evaluated
         )
+        # Chain .all() call
         .all()
     )
 
+    # Assign count = 0
     count = 0
+    # Iterate over stale_techniques
     for tech in stale_techniques:
+        # Check: not tech.review_required
         if not tech.review_required:
+            # Assign tech.review_required = True
             tech.review_required = True
+            # Assign count = 1
             count += 1
+            # Log info: "Marked %s as stale coverage", tech.mitre_id
             logger.info("Marked %s as stale coverage", tech.mitre_id)
 
+    # Check: count > 0
     if count > 0:
+        # Commit all pending changes to the database
         db.commit()
+        # Log info:
         logger.info(
+            # Literal argument value
             "Stale coverage detection complete — %d techniques flagged", count
         )
+    # Fallback: handle remaining cases
     else:
+        # Log info: "Stale coverage detection complete — no new stale
         logger.info("Stale coverage detection complete — no new stale techniques")
 
+    # Return count
     return count