doctrine: wire CI and fix existing violations

The doctrine tests have no CI coverage until this PR — they exist but nothing
runs them automatically. This adds a dedicated job so violations are caught
before merge.

Four use cases in the existing codebase pre-date the doctrine rules and were
never updated to conform. Without fixing them the CI job would fail immediately
on first run, defeating the purpose of adding it.

The initial doctrine tests only check for the existence of Request/Response
classes and an execute() method — they don't verify that execute() actually
uses them. Two new tests enforce the full contract: execute() must declare the
matching Request as its parameter and the matching Response as its return type.

With the signature checks in place, the scanner's blind spot became visible:
the contrib directory was listed in RESERVED_WORDS, but the scanner used that
list to skip directories entirely rather than just excluding them from being
bounded contexts themselves. This meant contrib/polling was never scanned. The
fix lets reserved-word directories still be treated as nested solution containers.

Author: absoludity

.github/workflows/python.yml

@@ -49,3 +49,17 @@ jobs:
 
       - name: Test
         run: make test-python-unit
+
+  doctrine:
+    name: Doctrine
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install dependencies
+        run: pip install -r requirements-dev.txt
+      - name: Doctrine tests
+        run: PYTHONPATH=src pytest src/julee/core/doctrine/

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "julee"
-version = "0.1.12"
+version = "0.1.13"
 description = "Julee - Clean architecture for accountable and transparent digital supply chains"
 readme = "README.md"
 requires-python = ">=3.11"

src/julee/__init__.py

@@ -1,3 +1,3 @@
 """Julee - Clean architecture for accountable and transparent digital supply chains."""
 
-__version__ = "0.1.12"
+__version__ = "0.1.13"

src/julee/api/services/system_initialization.py

@@ -14,6 +14,7 @@
 from typing import Any
 
 from julee.domain.use_cases.initialize_system_data import (
+    InitializeSystemDataRequest,
     InitializeSystemDataUseCase,
 )
 
@@ -128,7 +129,9 @@ async def _execute_system_data_initialization(
         try:
             self.logger.debug("Starting task: %s", task_name)
 
-            await self.initialize_system_data_use_case.execute()
+            await self.initialize_system_data_use_case.execute(
+                InitializeSystemDataRequest()
+            )
 
             results["tasks_completed"].append(task_name)
             results["metadata"][task_name] = {

src/julee/contrib/polling/apps/worker/pipelines.py

@@ -20,7 +20,10 @@
 from julee.contrib.polling.infrastructure.temporal.proxies import (
     WorkflowPollerServiceProxy,
 )
-from julee.contrib.polling.use_cases.poll_data import PollDataRequest, PollDataUseCase
+from julee.contrib.polling.use_cases.poll_data import (
+    PollDataRequest,
+    PollDataUseCase,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -123,16 +126,12 @@ async def run(
                 handler=self.get_handler(),
                 analyzer=self.get_analyzer(),
             )
-            result = await use_case.execute(request)
+            response = await use_case.execute(request)
 
-            self.endpoint_id = result.get("endpoint_id", self.endpoint_id)
-            self.has_new_data = result.get("detection_result", {}).get(
-                "has_new_data", False
-            )
+            self.endpoint_id = response.endpoint_id
+            self.has_new_data = response.new_items_found
             self.current_step = "completed"
 
-            result["completed_at"] = workflow.now().isoformat()
-
             workflow.logger.info(
                 "New data detection pipeline completed successfully",
                 extra={
@@ -141,7 +140,19 @@ async def run(
                 },
             )
 
-            return result
+            return {
+                "polling_result": {
+                    "content_hash": response.content_hash,
+                    "content": response.content,
+                    "polled_at": response.polled_at,
+                },
+                "detection_result": {
+                    "has_new_data": response.new_items_found,
+                    "current_hash": response.content_hash,
+                },
+                "endpoint_id": response.endpoint_id,
+                "completed_at": workflow.now().isoformat(),
+            }
 
         except Exception as e:
             self.current_step = "failed"

src/julee/contrib/polling/use_cases/poll_data.py

@@ -28,6 +28,17 @@ class PollDataRequest(BaseModel):
     previous_completion: dict | None = None
 
 
+class PollDataResponse(BaseModel):
+    """Output for PollDataUseCase."""
+
+    endpoint_id: str
+    content_hash: str
+    content: str
+    polled_at: str
+    new_items_found: bool
+    items_processed: int
+
+
 class PollDataUseCase:
     """
     Use case for polling an endpoint and detecting new data.
@@ -38,9 +49,8 @@ class PollDataUseCase:
     3. Compare with the previous run's hash (from previous_completion)
     4. If content has changed and an analyzer is set, identify new item IDs
     5. Delegate to the optional PollingResultHandler with the item IDs
-    6. Return a completion result dict in the same shape that
-       NewDataDetectionPipeline returns, so Temporal schedule
-       last-completion-result works unchanged.
+    6. Return a PollDataResponse; the pipeline builds the Temporal
+       last-completion-result dict from it.
 
     """
 
@@ -54,7 +64,7 @@ def __init__(
         self._handler = handler
         self._analyzer = analyzer
 
-    async def execute(self, request: PollDataRequest) -> dict:
+    async def execute(self, request: PollDataRequest) -> PollDataResponse:
         """
         Execute the poll-and-detect use case.
 
@@ -64,9 +74,7 @@ async def execute(self, request: PollDataRequest) -> dict:
                      for the first run).
 
         Returns:
-            Completion result dict with keys:
-              polling_result, detection_result, handler_acknowledgement,
-              endpoint_id
+            PollDataResponse with polling outcome and detection results.
         """
         config = request.config
         endpoint_id = config.endpoint_identifier
@@ -99,13 +107,14 @@ async def execute(self, request: PollDataRequest) -> dict:
         has_new_data = previous_hash != current_hash
 
         # Step 5: Analyze and invoke handler if new data detected
-        handler_acknowledgement = None
+        items_processed = 0
         if has_new_data:
             try:
                 item_ids = await self._analyzer.identify_new_items(
                     previous_data, current_content
                 )
-                handler_acknowledgement = await self._handler.handle_new_data(
+                items_processed = len(item_ids)
+                await self._handler.handle_new_data(
                     endpoint_id,
                     item_ids,
                     current_hash,
@@ -120,22 +129,13 @@ async def execute(self, request: PollDataRequest) -> dict:
                     },
                     exc_info=True,
                 )
-                # handler_acknowledgement stays None to signal the exception
 
         # Step 6: Return completion result
-        return {
-            "polling_result": {
-                "success": polling_result.success,
-                "content_hash": current_hash,
-                "content": current_content.decode("utf-8", errors="ignore"),
-                "polled_at": polled_at,
-                "content_length": len(current_content),
-            },
-            "detection_result": {
-                "has_new_data": has_new_data,
-                "previous_hash": previous_hash,
-                "current_hash": current_hash,
-            },
-            "handler_acknowledgement": handler_acknowledgement,
-            "endpoint_id": endpoint_id,
-        }
+        return PollDataResponse(
+            endpoint_id=endpoint_id,
+            content_hash=current_hash,
+            content=current_content.decode("utf-8", errors="ignore"),
+            polled_at=polled_at,
+            new_items_found=has_new_data,
+            items_processed=items_processed,
+        )

src/julee/core/doctrine/test_use_case.py

@@ -5,6 +5,7 @@
 """
 
 import importlib
+import inspect
 
 import pytest
 
@@ -216,3 +217,152 @@ async def test_all_use_cases_MUST_have_matching_response(self, repo):
         assert not violations, "Use cases missing matching responses:\n" + "\n".join(
             violations
         )
+
+    @pytest.mark.asyncio
+    async def test_execute_MUST_accept_matching_request(self, repo):
+        """execute() MUST declare its first parameter as {Prefix}Request.
+
+        Ensures the request class is part of the method's contract, not
+        just present in the module.
+        """
+        use_case = ListUseCasesUseCase(repo)
+        response = await use_case.execute(ListCodeArtifactsRequest())
+
+        bounded_contexts = await repo.list_all()
+        import_paths = {bc.slug: bc.import_path for bc in bounded_contexts}
+
+        violations = []
+        suffix_len = len(USE_CASE_SUFFIX)
+        for artifact in response.artifacts:
+            name = artifact.artifact.name
+            ctx = artifact.bounded_context
+            if name in GENERIC_BASE_CLASSES:
+                continue
+            if not name.endswith(USE_CASE_SUFFIX):
+                continue
+
+            prefix = name[:-suffix_len]
+            expected_request = f"{prefix}{REQUEST_SUFFIX}"
+
+            bc_import_path = import_paths.get(ctx)
+            cls = (
+                _resolve_class(bc_import_path, artifact.artifact.file, name)
+                if bc_import_path
+                else None
+            )
+
+            if cls is not None:
+                execute = getattr(cls, "execute", None)
+                if not callable(execute):
+                    continue
+                sig = inspect.signature(execute)
+                params = [p for p in sig.parameters.values() if p.name != "self"]
+                if not params:
+                    violations.append(
+                        f"{ctx}.{name}: execute() has no request parameter"
+                    )
+                    continue
+                annotation = params[0].annotation
+                actual_name = (
+                    annotation.__name__
+                    if hasattr(annotation, "__name__")
+                    else str(annotation)
+                )
+            else:
+                # Fall back to AST-parsed signature
+                execute_method = next(
+                    (m for m in artifact.artifact.methods if m.name == "execute"),
+                    None,
+                )
+                if execute_method is None:
+                    continue
+                if not execute_method.parameters:
+                    violations.append(
+                        f"{ctx}.{name}: execute() has no request parameter"
+                    )
+                    continue
+                actual_name = execute_method.parameters[0].type_annotation
+
+            if actual_name != expected_request:
+                violations.append(
+                    f"{ctx}.{name}: execute() first parameter is '{actual_name}'"
+                    f", expected '{expected_request}'"
+                )
+
+        assert not violations, "Use cases with wrong request type:\n" + "\n".join(
+            violations
+        )
+
+    @pytest.mark.asyncio
+    async def test_execute_MUST_return_matching_response(self, repo):
+        """execute() MUST declare its return type as {Prefix}Response.
+
+        Ensures the response class is actually wired into execute(), not
+        just present in the module.
+        """
+        use_case = ListUseCasesUseCase(repo)
+        response = await use_case.execute(ListCodeArtifactsRequest())
+
+        bounded_contexts = await repo.list_all()
+        import_paths = {bc.slug: bc.import_path for bc in bounded_contexts}
+
+        violations = []
+        suffix_len = len(USE_CASE_SUFFIX)
+        for artifact in response.artifacts:
+            name = artifact.artifact.name
+            ctx = artifact.bounded_context
+            if name in GENERIC_BASE_CLASSES:
+                continue
+            if not name.endswith(USE_CASE_SUFFIX):
+                continue
+
+            prefix = name[:-suffix_len]
+            expected_response = f"{prefix}{RESPONSE_SUFFIX}"
+
+            bc_import_path = import_paths.get(ctx)
+            cls = (
+                _resolve_class(bc_import_path, artifact.artifact.file, name)
+                if bc_import_path
+                else None
+            )
+
+            if cls is not None:
+                execute = getattr(cls, "execute", None)
+                if not callable(execute):
+                    continue
+                sig = inspect.signature(execute)
+                return_annotation = sig.return_annotation
+                if return_annotation is inspect.Parameter.empty:
+                    violations.append(
+                        f"{ctx}.{name}: execute() has no return annotation"
+                    )
+                    continue
+                actual_name = (
+                    return_annotation.__name__
+                    if hasattr(return_annotation, "__name__")
+                    else str(return_annotation)
+                )
+            else:
+                # Fall back to AST-parsed signature
+                execute_method = next(
+                    (m for m in artifact.artifact.methods if m.name == "execute"),
+                    None,
+                )
+                if execute_method is None:
+                    continue
+                if not execute_method.return_type:
+                    violations.append(
+                        f"{ctx}.{name}: execute() has no return annotation"
+                    )
+                    continue
+                actual_name = execute_method.return_type
+
+            if actual_name != expected_response:
+                violations.append(
+                    f"{ctx}.{name}: execute() returns '{actual_name}'"
+                    f", expected '{expected_response}'"
+                )
+
+        assert not violations, "Use cases with wrong return type:\n" + "\n".join(
+            violations
+        )

src/julee/core/infrastructure/repositories/introspection/bounded_context.py

@@ -235,14 +235,16 @@ def _discover_all(self) -> list[BoundedContext]:
                 continue
             if _is_gitignored(candidate, self.project_root):
                 continue
-            if candidate.name in RESERVED_WORDS:
-                continue
             if not self._is_python_package(candidate):
                 continue
 
+            # Reserved words cannot be bounded contexts themselves, but may
+            # still be nested solution containers (e.g. contrib/, apps/).
+            is_reserved = candidate.name in RESERVED_WORDS
+
             markers = self._detect_markers(candidate)
 
-            if self._is_bounded_context(markers):
+            if not is_reserved and self._is_bounded_context(markers):
                 # It's a bounded context
                 is_contrib = candidate.name == CONTRIB_DIR
                 context = BoundedContext(