fix: commit semantic repair changes

backend/src/services/dataset_review/clarification_engine.py

@@ -15,7 +15,7 @@
 # @INVARIANT: Only one active clarification question may exist at a time; skipped and expert-review items remain unresolved and visible.
 from __future__ import annotations
 
-# [DEF:ClarificationEngine.imports:Block]
+# [DEF:imports:Block]
 import uuid
 from dataclasses import dataclass, field
 from datetime import datetime
@@ -42,7 +42,7 @@ from src.models.dataset_review import (
 from src.services.dataset_review.repositories.session_repository import (
     DatasetReviewSessionRepository,
 )
-# [/DEF:ClarificationEngine.imports:Block]
+# [/DEF:imports:Block]
 
 
 # [DEF:ClarificationQuestionPayload:Class]
@@ -97,14 +97,14 @@ class ClarificationAnswerCommand:
 # @POST: Returned clarification state is persistence-backed and aligned with session readiness/recommended action.
 # @SIDE_EFFECT: Mutates clarification answers, session flags, and related clarification findings.
 class ClarificationEngine:
-    # [DEF:ClarificationEngine.__init__:Function]
+    # [DEF:ClarificationEngine_init:Function]
     # @COMPLEXITY: 2
     # @PURPOSE: Bind repository dependency for clarification persistence operations.
     def __init__(self, repository: DatasetReviewSessionRepository) -> None:
         self.repository = repository
-    # [/DEF:ClarificationEngine.__init__:Function]
+    # [/DEF:ClarificationEngine_init:Function]
 
-    # [DEF:ClarificationEngine.build_question_payload:Function]
+    # [DEF:build_question_payload:Function]
     # @COMPLEXITY: 4
     # @PURPOSE: Return the one active highest-priority clarification question payload with why-it-matters, current guess, and options.
     # @RELATION: [DEPENDS_ON] ->[ClarificationQuestion]
@@ -197,9 +197,9 @@ class ClarificationEngine:
                 },
             )
             return payload
-    # [/DEF:ClarificationEngine.build_question_payload:Function]
+    # [/DEF:build_question_payload:Function]
 
-    # [DEF:ClarificationEngine.record_answer:Function]
+    # [DEF:record_answer:Function]
     # @COMPLEXITY: 4
     # @PURPOSE: Persist one clarification answer before any pointer/readiness mutation and compute deterministic state impact.
     # @RELATION: [DEPENDS_ON] ->[ClarificationAnswer]
@@ -326,19 +326,19 @@ class ClarificationEngine:
                 session=session,
                 changed_findings=[changed_finding] if changed_finding else [],
             )
-    # [/DEF:ClarificationEngine.record_answer:Function]
+    # [/DEF:record_answer:Function]
 
-    # [DEF:ClarificationEngine.summarize_progress:Function]
-    # @COMPLEXITY: 3
+    # [DEF:summarize_progress:Function]
+    # @COMPLEXITY: 2
     # @PURPOSE: Produce a compact progress summary for pause/resume and completion UX.
     # @RELATION: [DEPENDS_ON] ->[ClarificationSession]
     def summarize_progress(self, clarification_session: ClarificationSession) -> str:
         resolved = self._count_resolved_questions(clarification_session)
         remaining = self._count_remaining_questions(clarification_session)
         return f"{resolved} resolved, {remaining} unresolved"
-    # [/DEF:ClarificationEngine.summarize_progress:Function]
+    # [/DEF:summarize_progress:Function]
 
-    # [DEF:ClarificationEngine._get_latest_clarification_session:Function]
+    # [DEF:_get_latest_clarification_session:Function]
     # @COMPLEXITY: 2
     # @PURPOSE: Select the latest clarification session for the current dataset review aggregate.
     def _get_latest_clarification_session(
@@ -353,10 +353,10 @@ class ClarificationEngine:
             reverse=True,
         )
         return ordered_sessions[0]
-    # [/DEF:ClarificationEngine._get_latest_clarification_session:Function]
+    # [/DEF:_get_latest_clarification_session:Function]
 
-    # [DEF:ClarificationEngine._find_question:Function]
-    # @COMPLEXITY: 1
+    # [DEF:_find_question:Function]
+    # @COMPLEXITY: 2
     # @PURPOSE: Resolve a clarification question from the active clarification aggregate.
     def _find_question(
         self,
@@ -367,9 +367,9 @@ class ClarificationEngine:
             if question.question_id == question_id:
                 return question
         return None
-    # [/DEF:ClarificationEngine._find_question:Function]
+    # [/DEF:_find_question:Function]
 
-    # [DEF:ClarificationEngine._select_next_open_question:Function]
+    # [DEF:_select_next_open_question:Function]
     # @COMPLEXITY: 2
     # @PURPOSE: Select the next unresolved question in deterministic priority order.
     def _select_next_open_question(
@@ -384,10 +384,10 @@ class ClarificationEngine:
             return None
         open_questions.sort(key=lambda item: (-int(item.priority), item.created_at, item.question_id))
         return open_questions[0]
-    # [/DEF:ClarificationEngine._select_next_open_question:Function]
+    # [/DEF:_select_next_open_question:Function]
 
-    # [DEF:ClarificationEngine._count_resolved_questions:Function]
-    # @COMPLEXITY: 1
+    # [DEF:_count_resolved_questions:Function]
+    # @COMPLEXITY: 2
     # @PURPOSE: Count questions whose answers fully resolved the ambiguity.
     def _count_resolved_questions(self, clarification_session: ClarificationSession) -> int:
         return sum(
@@ -395,10 +395,10 @@ class ClarificationEngine:
             for question in clarification_session.questions
             if question.state == QuestionState.ANSWERED
         )
-    # [/DEF:ClarificationEngine._count_resolved_questions:Function]
+    # [/DEF:_count_resolved_questions:Function]
 
-    # [DEF:ClarificationEngine._count_remaining_questions:Function]
-    # @COMPLEXITY: 1
+    # [DEF:_count_remaining_questions:Function]
+    # @COMPLEXITY: 2
     # @PURPOSE: Count questions still unresolved or deferred after clarification interaction.
     def _count_remaining_questions(self, clarification_session: ClarificationSession) -> int:
         return sum(
@@ -406,9 +406,9 @@ class ClarificationEngine:
             for question in clarification_session.questions
             if question.state in {QuestionState.OPEN, QuestionState.SKIPPED, QuestionState.EXPERT_REVIEW}
         )
-    # [/DEF:ClarificationEngine._count_remaining_questions:Function]
+    # [/DEF:_count_remaining_questions:Function]
 
-    # [DEF:ClarificationEngine._normalize_answer_value:Function]
+    # [DEF:_normalize_answer_value:Function]
     # @COMPLEXITY: 2
     # @PURPOSE: Validate and normalize answer payload based on answer kind and active question options.
     def _normalize_answer_value(
@@ -429,9 +429,9 @@ class ClarificationEngine:
         if answer_kind == AnswerKind.EXPERT_REVIEW:
             return normalized_answer_value or "expert_review"
         return normalized_answer_value
-    # [/DEF:ClarificationEngine._normalize_answer_value:Function]
+    # [/DEF:_normalize_answer_value:Function]
 
-    # [DEF:ClarificationEngine._build_impact_summary:Function]
+    # [DEF:_build_impact_summary:Function]
     # @COMPLEXITY: 2
     # @PURPOSE: Build a compact audit note describing how the clarification answer affects session state.
     def _build_impact_summary(
@@ -445,10 +445,10 @@ class ClarificationEngine:
         if answer_kind == AnswerKind.EXPERT_REVIEW:
             return f"Clarification for {question.topic_ref} was deferred for expert review."
         return f"Clarification for {question.topic_ref} recorded as '{answer_value}'."
-    # [/DEF:ClarificationEngine._build_impact_summary:Function]
+    # [/DEF:_build_impact_summary:Function]
 
-    # [DEF:ClarificationEngine._upsert_clarification_finding:Function]
-    # @COMPLEXITY: 3
+    # [DEF:_upsert_clarification_finding:Function]
+    # @COMPLEXITY: 2
     # @PURPOSE: Keep one finding per clarification topic aligned with answer outcome and unresolved visibility rules.
     # @RELATION: [DEPENDS_ON] ->[ValidationFinding]
     def _upsert_clarification_finding(
@@ -513,10 +513,10 @@ class ClarificationEngine:
             existing.title = "Clarification requires expert review"
 
         return existing
-    # [/DEF:ClarificationEngine._upsert_clarification_finding:Function]
+    # [/DEF:_upsert_clarification_finding:Function]
 
-    # [DEF:ClarificationEngine._derive_readiness_state:Function]
-    # @COMPLEXITY: 3
+    # [DEF:_derive_readiness_state:Function]
+    # @COMPLEXITY: 2
     # @PURPOSE: Recompute readiness after clarification mutation while preserving unresolved visibility semantics.
     # @RELATION: [DEPENDS_ON] ->[ClarificationSession]
     # @RELATION: [DEPENDS_ON] ->[DatasetReviewSession]
@@ -532,9 +532,9 @@ class ClarificationEngine:
             return ReadinessState.CLARIFICATION_NEEDED
 
         return ReadinessState.REVIEW_READY
-    # [/DEF:ClarificationEngine._derive_readiness_state:Function]
+    # [/DEF:_derive_readiness_state:Function]
 
-    # [DEF:ClarificationEngine._derive_recommended_action:Function]
+    # [DEF:_derive_recommended_action:Function]
     # @COMPLEXITY: 2
     # @PURPOSE: Recompute next-action guidance after clarification mutations.
     def _derive_recommended_action(self, session: DatasetReviewSession) -> RecommendedAction:
@@ -546,7 +546,7 @@ class ClarificationEngine:
         if clarification_session.remaining_count > 0:
             return RecommendedAction.START_CLARIFICATION
         return RecommendedAction.REVIEW_DOCUMENTATION
-    # [/DEF:ClarificationEngine._derive_recommended_action:Function]
+    # [/DEF:_derive_recommended_action:Function]
 # [/DEF:ClarificationEngine:Class]
 
 # [/DEF:ClarificationEngine:Module]