Introduce mypy check and modified git ci workflow to reproduce this test too

Author: fdidonato

.github/workflows/ci.yml

@@ -18,12 +18,29 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
 
-      # One shell session so `source venv/bin/activate` applies to pip, black, pytest.
-      - name: Install deps and run checks
+      # One shell session so `source venv/bin/activate` applies to all tools.
+      - name: Install dependencies
         run: |
           python -m venv venv
           source venv/bin/activate
           python -m pip install --upgrade pip
           pip install -e ".[dev,ui]"
+
+      - name: Lint & Format
+        run: |
+          source venv/bin/activate
+          ruff check .
           black --check .
-          pytest --maxfail=1 --disable-warnings -q
+
+      - name: Type Check
+        run: |
+          source venv/bin/activate
+          mypy moralstack --ignore-missing-imports
+
+      - name: Tests with Coverage
+        run: |
+          source venv/bin/activate
+          pytest --cov=moralstack --cov-report=xml --cov-report=term --maxfail=3
+
+      - name: Upload Coverage
+        uses: codecov/codecov-action@v4

.gitignore

@@ -19,6 +19,9 @@ env/
 
 # Pytest
 .pytest_cache/
+.coverage
+coverage.xml
+htmlcov/
 
 # mypy
 .mypy_cache/

.pre-commit-config.yaml

@@ -16,3 +16,11 @@ repos:
     hooks:
       - id: black
         language_version: python3.11
+
+  - repo: local
+    hooks:
+      - id: mypy
+        name: mypy
+        entry: mypy moralstack --ignore-missing-imports
+        language: system
+        pass_filenames: false

INSTALL.md

@@ -29,7 +29,7 @@ points.
 pip install -e ".[dev,ui]"
 ```
 
-**Development only (pytest, ruff):**
+**Development only (pytest, pytest-cov, ruff, black, mypy):**
 
 ```bash
 pip install -e .[dev]

README.md

@@ -7,6 +7,8 @@
 ![Status](https://img.shields.io/badge/status-research--stage-yellow)
 ![Compliance](https://img.shields.io/badge/benchmark-98.8%25%20compliance-brightgreen)
 ![Model](https://img.shields.io/badge/model-GPT--4o-412991)
+[![CI](https://github.com/fdidonato/moralstack/actions/workflows/ci.yml/badge.svg)](https://github.com/fdidonato/moralstack/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/fdidonato/moralstack/graph/badge.svg)](https://codecov.io/gh/fdidonato/moralstack)
 
 MoralStack is a governance layer that decides **whether**, **how**, and **under what constraints** a response should be
 generated before text generation starts.

docs/DEVELOPMENT.md

@@ -11,13 +11,14 @@ pip install -e .[dev]
 ## Tools
 
 - **pytest** — Run tests: `pytest`
+- **pytest-cov** — Coverage reports: `pytest --cov=moralstack --cov-report=xml --cov-report=term`
 - **ruff** — Linting and formatting: `ruff check .` / `ruff format .`
 - **black** — Format check: `black --check .` (or `black .` to reformat)
 - **mypy** — Type checking: `mypy moralstack`
 
 ## Pre-commit Hooks
 
-Pre-commit hooks run cheap checks (format, lint, whitespace) automatically before every commit.
+Pre-commit hooks run automated checks (format, lint, whitespace, type checks) before every commit.
 
 **Setup (one-time):**
 
@@ -38,11 +39,13 @@ pre-commit run --all-files
 git commit --no-verify
 ```
 
-Active hooks: `trailing-whitespace`, `end-of-file-fixer`, `ruff check --fix`, `black`.
+Active hooks: `trailing-whitespace`, `end-of-file-fixer`, `ruff check --fix`, `black`, `mypy moralstack`.
 
 ## CI
 
-The workflow in `.github/workflows/ci.yml` runs tests on Python 3.11 and 3.12 with `pip install -e .[dev]` and `pytest`.
+The workflow in `.github/workflows/ci.yml` runs on Python 3.11 and 3.12 with `pip install -e .[dev,ui]`, then executes:
+`ruff check .`, `black --check .`, `mypy moralstack --ignore-missing-imports`, and `pytest --cov=moralstack
+--cov-report=xml --cov-report=term --maxfail=3`.
 
 ## Generated Artifacts
 

docs/architecture_spec.md

@@ -783,6 +783,7 @@ class ResponseMetadata:
     intent_clarity: str = ""
     misuse_plausibility: str = ""
     actionability_risk: str = ""
+    decision_correctness: dict[str, Any] | None = None  # optional DCF payload (diagnostics.attach_decision_correctness)
 ```
 
 **Construction**: ResponseMetadata must be built via factory methods so all paths produce consistent metadata. Do not construct `ResponseMetadata` manually for request flows. Use:

docs/modules/orchestrator.md

@@ -402,6 +402,7 @@ class ResponseMetadata:
     intent_clarity: str  # LOW | MEDIUM | HIGH (semantic signals)
     misuse_plausibility: str  # LOW | MEDIUM | HIGH
     actionability_risk: str  # LOW | MEDIUM | HIGH
+    decision_correctness: dict[str, Any] | None  # optional DCF payload from diagnostics
 ```
 
 **Construction**: Always build metadata via factory methods for consistency across paths (fast, deliberative, safe_complete, domain_excluded, system error). Use `ResponseMetadata.from_decision(...)` for flows that have a `Decision` (and optional `DecisionExplanation`); use `ResponseMetadata.for_system_error(...)`, `for_domain_excluded(...)`, or `for_fail_safe(...)` for timeout, domain-excluded, and FAIL_SAFE fallback respectively. See `docs/architecture_spec.md` (ResponseMetadata Construction) for the full list.

moralstack/cli/mocks.py

@@ -2,7 +2,7 @@
 Mock modules for MoralStack CLI testing without API.
 """
 
-from typing import Any
+from typing import Any, Literal
 
 
 class MockPolicy:
@@ -66,32 +66,55 @@ def estimate(self, prompt: str) -> Any:
 class MockCritic:
     """Constitutional critic mock."""
 
-    def critique(self, request: Any, response: str, constitution: Any = None, **kwargs) -> Any:
+    def critique(self, request: Any, response: str, constitution: Any = None, **kwargs: Any) -> Any:
         """Mock critique."""
         from dataclasses import dataclass, field
 
         @dataclass
         class MockCritique:
-            violations: list = field(default_factory=list)
+            violations: list[Any] = field(default_factory=list)
             severity_score: float = 0.0
             has_critical_violations: bool = False
             revision_guidance: str = ""
 
         return MockCritique()
 
+    def critique_with_relevant_principles(
+        self,
+        request: str,
+        response: str,
+        domain: str | None = None,
+        request_id: str = "",
+        delib_context: Any = None,
+        context_mode: Literal["full", "thin"] = "full",
+        previous_violations: str = "",
+        previous_guidance: str = "",
+    ) -> Any:
+        """Mock path aligned with LLMConstitutionalCritic (delegates to critique)."""
+        return self.critique(
+            request,
+            response,
+            None,
+            request_id=request_id,
+            delib_context=delib_context,
+            context_mode=context_mode,
+            previous_violations=previous_violations,
+            previous_guidance=previous_guidance,
+        )
+
 
 class MockSimulator:
     """Consequence simulator mock."""
 
-    def simulate(self, request: Any, response: str, num_scenarios: int = 3, **kwargs) -> list:
+    def simulate(self, request: Any, response: str, num_scenarios: int = 3, **kwargs: Any) -> list[Any]:
         """Simulates mock consequences."""
         return []
 
 
 class MockHindsight:
     """Hindsight evaluator mock."""
 
-    def evaluate(self, request: str, response: str, consequences: list, **kwargs) -> Any:
+    def evaluate(self, request: str, response: str, consequences: list[Any], **kwargs: Any) -> Any:
         """Mock hindsight evaluation."""
         from dataclasses import dataclass, field
 
@@ -111,7 +134,7 @@ class MockAggregatedHindsight:
 
         @dataclass
         class MockHindsightResult:
-            evaluations: list = field(default_factory=list)
+            evaluations: list[Any] = field(default_factory=list)
             aggregated: MockAggregatedHindsight = field(default_factory=MockAggregatedHindsight)
 
         return MockHindsightResult()
@@ -120,19 +143,19 @@ class MockHindsightResult:
 class MockPerspectives:
     """Perspective ensemble mock."""
 
-    def evaluate(self, request: Any, response: str, **kwargs) -> Any:
+    def evaluate(self, request: Any, response: str, **kwargs: Any) -> Any:
         """Mock perspectives evaluation."""
         from dataclasses import dataclass, field
 
         @dataclass
         class MockPerspectiveAggregation:
             overall_score: float = 0.8
-            concerns: list = field(default_factory=list)
+            concerns: list[Any] = field(default_factory=list)
             consensus_level: float = 0.9
 
         @dataclass
         class MockPerspectiveResult:
-            results: list = field(default_factory=list)
+            results: list[Any] = field(default_factory=list)
             aggregation: MockPerspectiveAggregation = field(default_factory=MockPerspectiveAggregation)
 
         return MockPerspectiveResult()
@@ -147,10 +170,10 @@ def get_constitution(self, domain: str | None = None) -> Any:
 
         @dataclass
         class MockConstitution:
-            principles: list = field(default_factory=list)
+            principles: list[Any] = field(default_factory=list)
 
         return MockConstitution()
 
-    def get_relevant_principles(self, query: str, top_k: int = 10, domain: str | None = None) -> list:
+    def get_relevant_principles(self, query: str, top_k: int = 10, domain: str | None = None) -> list[Any]:
         """Returns empty list (no principles needed for mock)."""
         return []

moralstack/cli/models.py

@@ -77,9 +77,9 @@ class PhaseResult:
     output_summary: str
     decision: Optional[str] = None
     decision_reason: Optional[str] = None
-    details: dict = field(default_factory=dict)
-    errors: list = field(default_factory=list)
-    warnings: list = field(default_factory=list)
+    details: dict[str, Any] = field(default_factory=dict)
+    errors: list[str] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
 
 
 @dataclass
@@ -99,18 +99,18 @@ class TraceParseResult:
     phase_type: PhaseType
     decision: Optional[str] = None
     decision_reason: Optional[str] = None
-    details: dict = field(default_factory=dict)
-    errors: list = field(default_factory=list)
-    warnings: list = field(default_factory=list)
+    details: dict[str, Any] = field(default_factory=dict)
+    errors: list[str] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
     risk_score: Optional[float] = None
     risk_category: Optional[str] = None
-    draft_revisions: list = field(default_factory=list)
+    draft_revisions: list[DraftRevision] = field(default_factory=list)
 
 
-def _parse_risk_trace(call: dict) -> TraceParseResult:
+def _parse_risk_trace(call: dict[str, Any]) -> TraceParseResult:
     """Parse risk_estimator call into trace phase data."""
     response = call.get("full_response", call.get("response", ""))
-    details: dict = {}
+    details: dict[str, Any] = {}
     risk_score: Optional[float] = None
     risk_category: Optional[str] = None
 
@@ -155,7 +155,7 @@ def _parse_risk_trace(call: dict) -> TraceParseResult:
     )
 
 
-def _parse_policy_trace(call: dict, current_cycle: int) -> Optional[TraceParseResult]:
+def _parse_policy_trace(call: dict[str, Any], current_cycle: int) -> Optional[TraceParseResult]:
     """Parse policy call into trace phase data."""
     action = call.get("action", "")
     prompt = call.get("full_prompt", call.get("prompt", ""))
@@ -213,12 +213,12 @@ def _parse_policy_trace(call: dict, current_cycle: int) -> Optional[TraceParseRe
     return None
 
 
-def _parse_critic_trace(call: dict) -> TraceParseResult:
+def _parse_critic_trace(call: dict[str, Any]) -> TraceParseResult:
     """Parse critic call into trace phase data."""
     action = call.get("action", "")
     response = call.get("full_response", call.get("response", ""))
-    details: dict = {}
-    errors: list = []
+    details: dict[str, Any] = {}
+    errors: list[str] = []
     decision = None
     decision_reason = None
 
@@ -275,10 +275,10 @@ def _parse_critic_trace(call: dict) -> TraceParseResult:
     )
 
 
-def _parse_simulator_trace(call: dict) -> TraceParseResult:
+def _parse_simulator_trace(call: dict[str, Any]) -> TraceParseResult:
     """Parse simulator call into trace phase data."""
     response = call.get("full_response", call.get("response", ""))
-    details: dict = {}
+    details: dict[str, Any] = {}
     decision = None
     decision_reason = None
 
@@ -342,10 +342,10 @@ def _parse_simulator_trace(call: dict) -> TraceParseResult:
     )
 
 
-def _parse_hindsight_trace(call: dict) -> TraceParseResult:
+def _parse_hindsight_trace(call: dict[str, Any]) -> TraceParseResult:
     """Parse hindsight call into trace phase data."""
     response = call.get("full_response", call.get("response", ""))
-    details: dict = {}
+    details: dict[str, Any] = {}
     decision = None
     decision_reason = None
 
@@ -381,10 +381,10 @@ def _parse_hindsight_trace(call: dict) -> TraceParseResult:
     )
 
 
-def _parse_perspectives_trace(call: dict) -> TraceParseResult:
+def _parse_perspectives_trace(call: dict[str, Any]) -> TraceParseResult:
     """Parse perspectives call into trace phase data."""
     response = call.get("full_response", call.get("response", ""))
-    details: dict = {}
+    details: dict[str, Any] = {}
     decision = None
     decision_reason = None
 
@@ -436,13 +436,13 @@ class DeliberationTrace:
     # Risk estimation
     risk_score: float = 0.0
     risk_category: str = ""
-    risk_signals: list = field(default_factory=list)
+    risk_signals: list[str] = field(default_factory=list)
 
     # Phases
-    phases: list = field(default_factory=list)
+    phases: list[PhaseResult] = field(default_factory=list)
 
     # Draft revision history
-    draft_history: list = field(default_factory=list)  # List[DraftRevision]
+    draft_history: list[DraftRevision] = field(default_factory=list)
 
     # Final outcome
     response_type: str = ""
@@ -451,12 +451,12 @@ class DeliberationTrace:
     converged: bool = False
 
     # Errors and warnings
-    errors: list = field(default_factory=list)
-    warnings: list = field(default_factory=list)
+    errors: list[str] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
 
     # Constitution
-    relevant_principles: list = field(default_factory=list)
-    triggered_principles: list = field(default_factory=list)
+    relevant_principles: list[str] = field(default_factory=list)
+    triggered_principles: list[str] = field(default_factory=list)
 
     def add_phase(self, phase: PhaseResult) -> None:
         """Adds a phase to the trace."""
@@ -466,11 +466,11 @@ def total_duration_ms(self) -> float:
         """Total duration in milliseconds."""
         if self.end_time > 0 and self.start_time > 0:
             return (self.end_time - self.start_time) * 1000
-        return sum(p.duration_ms for p in self.phases)
+        return float(sum(p.duration_ms for p in self.phases))
 
-    def get_phases_by_cycle(self) -> dict:
+    def get_phases_by_cycle(self) -> dict[int, list[PhaseResult]]:
         """Groups phases by cycle."""
-        by_cycle: dict[int, list[Any]] = {}
+        by_cycle: dict[int, list[PhaseResult]] = {}
         for phase in self.phases:
             if phase.cycle not in by_cycle:
                 by_cycle[phase.cycle] = []