+

backend/src/plugins/migration.py

@@ -8,6 +8,10 @@
 # @RELATION: DEPENDS_ON -> MigrationEngine
 # @RELATION: DEPENDS_ON -> IdMappingService
 # @RELATION: USES -> TaskContext
+# @PRE: Plugin loader can resolve infrastructure dependencies and execution requests provide validated migration context.
+# @POST: Plugin metadata remains stable and migration execution preserves mapped-environment import guarantees.
+# @SIDE_EFFECT: Reads config, opens database sessions, creates temporary artifacts, and triggers Superset export/import workflows.
+# @DATA_CONTRACT: Input[TaskContext{from_env,to_env,dashboard_regex,replace_db_config,from_db_id,to_db_id,passwords?}] -> Output[MigrationResult|artifact set]
 # @INVARIANT: Dashboards must never be imported with unmapped/source DB connections to prevent data leaks or cross-environment pollution.
 
 from typing import Dict, Any, Optional

backend/src/services/clean_release/compliance_execution_service.py

@@ -3,10 +3,14 @@
 # @SEMANTICS: clean-release, compliance, execution, stages, immutable-evidence
 # @PURPOSE: Create and execute compliance runs with trusted snapshots, deterministic stages, violations and immutable report persistence.
 # @LAYER: Domain
-# @RELATION: [DEPENDS_ON] ->[RepositoryRelations]
+# @RELATION: DEPENDS_ON -> RepositoryRelations
-# @RELATION: [DEPENDS_ON] ->[PolicyResolutionService]
+# @RELATION: DEPENDS_ON -> PolicyResolutionService
-# @RELATION: [DEPENDS_ON] ->[ComplianceStages]
+# @RELATION: DEPENDS_ON -> ComplianceStages
-# @RELATION: [DEPENDS_ON] ->[ReportBuilder]
+# @RELATION: DEPENDS_ON -> ReportBuilder
+# @PRE: Repository adapters, trusted policy resolution, and deterministic stage implementations are available for the run request.
+# @POST: Candidate-scoped compliance runs persist stage evidence, terminal status, and immutable report artifacts when execution succeeds.
+# @SIDE_EFFECT: Persists runs, stage results, violations, and reports through repository adapters and audit helpers.
+# @DATA_CONTRACT: Input[candidate_id, requested_by, manifest_id?, policy snapshots, stage results] -> Output[ComplianceExecutionResult]
 # @INVARIANT: A run binds to exactly one candidate/manifest/policy/registry snapshot set.
 
 from __future__ import annotations

backend/src/services/clean_release/report_builder.py

@@ -12,10 +12,10 @@
 # @TEST_EDGE: counter_mismatch -> blocking counter cannot exceed total violations counter
 # @TEST_EDGE: missing_operator_summary -> non-terminal run prevents report creation and summary generation
 # @TEST_INVARIANT: blocking_count_le_total_count -> VERIFIED_BY: [counter_mismatch, empty_violations_for_blocked]
-# @DATA_CONTRACT: Manifest -> Report
+# @DATA_CONTRACT: Input[ComplianceRun, List[ComplianceViolation]] -> Output[ComplianceReport]
-# @PRE: ManifestService and compliance data are available
+# @PRE: Compliance run is terminal and repository persistence is available for report storage.
-# @POST: Report with generated summary and @SIDE_EFFECT': 
+# @POST: Returns immutable report payloads with consistent violation counters and operator summary content.
-# @SIDE_EFFECT: Writes report artifacts to database, generates audit trail
+# @SIDE_EFFECT: Writes report artifacts to repository when persistence helpers are invoked.
 
 from __future__ import annotations
 

frontend/src/lib/components/assistant/AssistantChatPanel.svelte

@@ -9,6 +9,10 @@
    * @RELATION: BINDS_TO -> DatasetReviewWorkspace
    * @RELATION: DISPATCHES -> taskDrawer
    * @SEMANTICS: assistant-chat, confirmation, long-running-task, progress-tracking
+   * @PRE: Assistant chat store, API adapters, and optional dataset review session context are initialized before the panel becomes interactive.
+   * @POST: User and assistant message state, conversation history, and task affordances stay synchronized with the active conversation scope.
+   * @SIDE_EFFECT: Reads and mutates assistant conversation state, may navigate to review routes, opens task drawer affordances, and emits toast feedback.
+   * @DATA_CONTRACT: Input[{variant,className,assistantChatStore,datasetReviewSessionId?}] -> Output[{messages,conversations,conversationId,llmReady,panelVisible}]
    * @INVARIANT: User commands and assistant responses are appended in chronological order.
    * @INVARIANT: Risky operations are executed only through explicit confirm action.
    * @UX_STATE: Closed -> Panel is hidden when variant is drawer.

frontend/src/lib/components/health/PolicyForm.svelte

@@ -3,8 +3,9 @@
 @COMPLEXITY: 3
 @PURPOSE: Form for creating and editing validation policies.
 @LAYER: UI
-@RELATION: DISPATCHES -> onSave
+@RELATION: DEPENDS_ON -> ValidationPolicy
-@RELATION: DISPATCHES -> onCancel
+@PRE: Parent provides callable onSave/onCancel handlers and an environments collection that may be empty but remains array-like.
+@POST: Form submission forwards the current draft to onSave and cancel delegates dismissal to the parent callback without mutating external state directly.
 
 @UX_STATE: Idle -> Displays the policy form.
 @UX_STATE: Submitting -> Disables inputs and shows a loading state.