fix repo place

{
        "file": "frontend/src/components/__tests__/task_log_viewer.test.js",
        "verdict": "APPROVED",
        "rejection_reason": "NONE",
        "audit_details": {
            "target_invoked": true,
            "pre_conditions_tested": true,
            "post_conditions_tested": true,
            "test_fixture_used": true,
            "edges_covered": true,
            "invariants_verified": true,
            "ux_states_tested": true,
            "semantic_anchors_present": true
        },
        "coverage_summary": {
            "total_edges": 2,
            "edges_tested": 2,
            "total_invariants": 1,
            "invariants_tested": 1,
            "total_ux_states": 3,
            "ux_states_tested": 3
        },
        "tier_compliance": {
            "source_tier": "CRITICAL",
            "meets_tier_requirements": true
        },
        "feedback": "Remediation successful: test tier matches CRITICAL, missing missing @TEST_EDGE no_task_id coverage added, test for @UX_FEEDBACK (autoScroll) added properly, missing inline=false (show=true) tested properly. Semantic RELATION tag fixed to VERIFIES."
    },
    {
        "file": "frontend/src/lib/components/reports/__tests__/report_card.ux.test.js",
        "verdict": "APPROVED",
        "rejection_reason": "NONE",
        "audit_details": {
            "target_invoked": true,
            "pre_conditions_tested": true,
            "post_conditions_tested": true,
            "test_fixture_used": true,
            "edges_covered": true,
            "invariants_verified": true,
            "ux_states_tested": true,
            "semantic_anchors_present": true
        },
        "coverage_summary": {
            "total_edges": 2,
            "edges_tested": 2,
            "total_invariants": 1,
            "invariants_tested": 1,
            "total_ux_states": 2,
            "ux_states_tested": 2
        },
        "tier_compliance": {
            "source_tier": "CRITICAL",
            "meets_tier_requirements": true
        },
        "feedback": "Remediation successful: @TEST_EDGE random_status and @TEST_EDGE empty_report_object tests explicitly assert on outcomes, @TEST_FIXTURE tested completely, Test tier switched to CRITICAL."
    },
    {
        "file": "backend/tests/test_logger.py",
        "verdict": "APPROVED",
        "rejection_reason": "NONE",
        "audit_details": {
            "target_invoked": true,
            "pre_conditions_tested": true,
            "post_conditions_tested": true,
            "test_fixture_used": true,
            "edges_covered": true,
            "invariants_verified": true,
            "ux_states_tested": false,
            "semantic_anchors_present": true
        },
        "coverage_summary": {
            "total_edges": 0,
            "edges_tested": 0,
            "total_invariants": 0,
            "invariants_tested": 0,
            "total_ux_states": 0,
            "ux_states_tested": 0
        },
        "tier_compliance": {
            "source_tier": "STANDARD",
            "meets_tier_requirements": true
        },
        "feedback": "Remediation successful: Test module semantic anchors added [DEF] and [/DEF] explicitly. Added missing @TIER tag and @RELATION: VERIFIES -> src/core/logger.py at the top of the file."
    }
]

.agent/workflows/audit-test.md

@@ -6,7 +6,7 @@ description: Audit AI-generated unit tests. Your goal is to aggressively search
 **OBJECTIVE:** Audit AI-generated unit tests. Your goal is to aggressively search for "Test Tautologies", "Logic Echoing", and "Contract Negligence". You are the final gatekeeper. If a test is meaningless, you MUST reject it.
 
 **INPUT:**
-1. SOURCE CODE (with GRACE-Poly `[DEF]` Contract: `@PRE`, `@POST`, `@TEST_DATA`).
+1. SOURCE CODE (with GRACE-Poly `[DEF]` Contract: `@PRE`, `@POST`, `@TEST_CONTRACT`, `@TEST_FIXTURE`, `@TEST_EDGE`, `@TEST_INVARIANT`).
 2. GENERATED TEST CODE.
 
 ### I. CRITICAL ANTI-PATTERNS (REJECT IMMEDIATELY IF FOUND):
@@ -17,7 +17,7 @@ description: Audit AI-generated unit tests. Your goal is to aggressively search
 
 2. **The Logic Mirror (Echoing):**
    - *Definition:* The test re-implements the exact same algorithmic logic found in the source code to calculate the `expected_result`. If the original logic is flawed, the test will falsely pass.
-   - *Rule:* Tests must assert against **static, predefined outcomes** (from `@TEST_DATA` or explicit constants), NOT dynamically calculated outcomes using the same logic as the source.
+   - *Rule:* Tests must assert against **static, predefined outcomes** (from `@TEST_FIXTURE`, `@TEST_EDGE`, `@TEST_INVARIANT` or explicit constants), NOT dynamically calculated outcomes using the same logic as the source.
 
 3. **The "Happy Path" Illusion:**
    - *Definition:* The test suite only checks successful executions but ignores the `@PRE` conditions (Negative Testing).
@@ -26,26 +26,78 @@ description: Audit AI-generated unit tests. Your goal is to aggressively search
 4. **Missing Post-Condition Verification:**
    - *Definition:* The test calls the function but only checks the return value, ignoring `@SIDE_EFFECT` or `@POST` state changes (e.g., failing to verify that a DB call was made or a Store was updated).
 
-### II. AUDIT CHECKLIST
+5. **Missing Edge Case Coverage:**
+   - *Definition:* The test suite ignores `@TEST_EDGE` scenarios defined in the contract.
+   - *Rule:* Every `@TEST_EDGE` in the source contract MUST have a corresponding test case.
+
+6. **Missing Invariant Verification:**
+   - *Definition:* The test suite does not verify `@TEST_INVARIANT` conditions.
+   - *Rule:* Every `@TEST_INVARIANT` MUST be verified by at least one test that attempts to break it.
+
+7. **Missing UX State Testing (Svelte Components):**
+   - *Definition:* For Svelte components with `@UX_STATE`, the test suite does not verify state transitions.
+   - *Rule:* Every `@UX_STATE` transition MUST have a test verifying the visual/behavioral change.
+   - *Check:* `@UX_FEEDBACK` mechanisms (toast, shake, color) must be tested.
+   - *Check:* `@UX_RECOVERY` mechanisms (retry, clear input) must be tested.
+
+### II. SEMANTIC PROTOCOL COMPLIANCE
+
+Verify the test file follows GRACE-Poly semantics:
+
+1. **Anchor Integrity:**
+   - Test file MUST start with `[DEF:__tests__/test_name:Module]`
+   - Test file MUST end with `[/DEF:__tests__/test_name:Module]`
+
+2. **Required Tags:**
+   - `@RELATION: VERIFIES -> <path_to_source>` must be present
+   - `@PURPOSE:` must describe what is being tested
+
+3. **TIER Alignment:**
+   - If source is `@TIER: CRITICAL`, test MUST cover all `@TEST_CONTRACT`, `@TEST_FIXTURE`, `@TEST_EDGE`, `@TEST_INVARIANT`
+   - If source is `@TIER: STANDARD`, test MUST cover `@PRE` and `@POST`
+   - If source is `@TIER: TRIVIAL`, basic smoke test is acceptable
+
+### III. AUDIT CHECKLIST
 
 Evaluate the test code against these criteria:
 1. **Target Invocation:** Does the test actually import and call the function/component declared in the `@RELATION: VERIFIES` tag?
 2. **Contract Alignment:** Does the test suite cover 100% of the `@PRE` (negative tests) and `@POST` (assertions) conditions from the source contract?
-3. **Data Usage:** Does the test use the exact scenarios defined in `@TEST_DATA`?
-4. **Mocking Sanity:** Are external dependencies mocked correctly WITHOUT mocking the system under test itself?
+3. **Test Contract Compliance:** Does the test follow the interface defined in `@TEST_CONTRACT`?
+4. **Data Usage:** Does the test use the exact scenarios defined in `@TEST_FIXTURE`?
+5. **Edge Coverage:** Are all `@TEST_EDGE` scenarios tested?
+6. **Invariant Coverage:** Are all `@TEST_INVARIANT` conditions verified?
+7. **UX Coverage (if applicable):** Are all `@UX_STATE`, `@UX_FEEDBACK`, `@UX_RECOVERY` tested?
+8. **Mocking Sanity:** Are external dependencies mocked correctly WITHOUT mocking the system under test itself?
+9. **Semantic Anchor:** Does the test file have proper `[DEF]` and `[/DEF]` anchors?
 
-### III. OUTPUT FORMAT
+### IV. OUTPUT FORMAT
 
 You MUST respond strictly in the following JSON format. Do not add markdown blocks outside the JSON.
 
 {
   "verdict": "APPROVED" | "REJECTED",
-  "rejection_reason": "TAUTOLOGY" | "LOGIC_MIRROR" | "WEAK_CONTRACT_COVERAGE" | "OVER_MOCKED" | "NONE",
+  "rejection_reason": "TAUTOLOGY" | "LOGIC_MIRROR" | "WEAK_CONTRACT_COVERAGE" | "OVER_MOCKED" | "MISSING_EDGES" | "MISSING_INVARIANTS" | "MISSING_UX_TESTS" | "SEMANTIC_VIOLATION" | "NONE",
   "audit_details": {
     "target_invoked": true/false,
     "pre_conditions_tested": true/false,
     "post_conditions_tested": true/false,
-    "test_data_used": true/false
+    "test_fixture_used": true/false,
+    "edges_covered": true/false,
+    "invariants_verified": true/false,
+    "ux_states_tested": true/false,
+    "semantic_anchors_present": true/false
+  },
+  "coverage_summary": {
+    "total_edges": number,
+    "edges_tested": number,
+    "total_invariants": number,
+    "invariants_tested": number,
+    "total_ux_states": number,
+    "ux_states_tested": number
+  },
+  "tier_compliance": {
+    "source_tier": "CRITICAL" | "STANDARD" | "TRIVIAL",
+    "meets_tier_requirements": true/false
   },
   "feedback": "Strict, actionable feedback for the test generator agent. Explain exactly which anti-pattern was detected and how to fix it."
 }

.agent/workflows/read_semantic.md

@@ -1,4 +1,4 @@
 ---
 description: USE SEMANTIC
 ---
-Прочитай .specify/memory/semantics.md (или .ai/standards/semantics.md, если не найден). ОБЯЗАТЕЛЬНО используй его при разработке
+Прочитай .ai/standards/semantics.md. ОБЯЗАТЕЛЬНО используй его при разработке

.agent/workflows/speckit.analyze.md

@@ -63,6 +63,7 @@ Load only the minimal necessary context from each artifact:
 **From constitution:**
 
 - Load `.ai/standards/constitution.md` for principle validation
+    - Load `.ai/standards/semantics.md` for technical standard validation
 
 ### 3. Build Semantic Models
 

.agent/workflows/speckit.fix.md

@@ -20,7 +20,7 @@ Analyze test failure reports, identify root causes, and fix implementation issue
 
 1. **USE CODER MODE**: Always switch to `coder` mode for code fixes
 2. **SEMANTIC PROTOCOL**: Never remove semantic annotations ([DEF], @TAGS). Only update code logic.
-3. **TEST DATA**: If tests use @TEST_DATA fixtures, preserve them when fixing
+3. **TEST DATA**: If tests use @TEST_ fixtures, preserve them when fixing
 4. **NO DELETION**: Never delete existing tests or semantic annotations
 5. **REPORT FIRST**: Always write a fix report before making changes
 

.agent/workflows/speckit.implement.md

@@ -53,6 +53,15 @@ You **MUST** consider the user input before proceeding (if not empty).
    - **IF EXISTS**: Read research.md for technical decisions and constraints
    - **IF EXISTS**: Read quickstart.md for integration scenarios
 
+3. Load and analyze the implementation context:
+    - **REQUIRED**: Read `.ai/standards/semantics.md` for strict coding standards and contract requirements
+    - **REQUIRED**: Read tasks.md for the complete task list and execution plan
+    - **REQUIRED**: Read plan.md for tech stack, architecture, and file structure
+    - **IF EXISTS**: Read data-model.md for entities and relationships
+    - **IF EXISTS**: Read contracts/ for API specifications and test requirements
+    - **IF EXISTS**: Read research.md for technical decisions and constraints
+    - **IF EXISTS**: Read quickstart.md for integration scenarios
+
 4. **Project Setup Verification**:
    - **REQUIRED**: Create/verify ignore files based on actual project setup:
 
@@ -111,7 +120,13 @@ You **MUST** consider the user input before proceeding (if not empty).
    - **Validation checkpoints**: Verify each phase completion before proceeding
 
 7. Implementation execution rules:
-   - **Setup first**: Initialize project structure, dependencies, configuration
+    - **Strict Adherence**: Apply `.ai/standards/semantics.md` rules:
+      - Every file MUST start with a `[DEF:id:Type]` header and end with a closing `[/DEF:id:Type]` anchor.
+      - Include `@TIER` and define contracts (`@PRE`, `@POST`).
+      - For Svelte components, use `@UX_STATE`, `@UX_FEEDBACK`, `@UX_RECOVERY`, and explicitly declare reactivity with `@UX_REATIVITY: State: $state, Derived: $derived`.
+      - **Molecular Topology Logging**: Use prefixes `[EXPLORE]`, `[REASON]`, `[REFLECT]` in logs to trace logic.
+    - **CRITICAL Contracts**: If a task description contains a contract summary (e.g., `CRITICAL: PRE: ..., POST: ...`), these constraints are **MANDATORY** and must be strictly implemented in the code using guards/assertions (if applicable per protocol).
+    - **Setup first**: Initialize project structure, dependencies, configuration
    - **Tests before code**: If you need to write tests for contracts, entities, and integration scenarios
    - **Core development**: Implement models, services, CLI commands, endpoints
    - **Integration work**: Database connections, middleware, logging, external services

.agent/workflows/speckit.plan.md

@@ -22,7 +22,7 @@ You **MUST** consider the user input before proceeding (if not empty).
 
 1. **Setup**: Run `.specify/scripts/bash/setup-plan.sh --json` from repo root and parse JSON for FEATURE_SPEC, IMPL_PLAN, SPECS_DIR, BRANCH. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
 
-2. **Load context**: Read FEATURE_SPEC and `.ai/standards/constitution.md`. Load IMPL_PLAN template (already copied).
+2. **Load context**: Read `.ai/ROOT.md` and `.ai/PROJECT_MAP.md` to understand the project structure and navigation. Then read required standards: `.ai/standards/constitution.md` and `.ai/standards/semantics.md`. Load IMPL_PLAN template.
 
 3. **Execute plan workflow**: Follow the structure in IMPL_PLAN template to:
    - Fill Technical Context (mark unknowns as "NEEDS CLARIFICATION")
@@ -64,16 +64,30 @@ You **MUST** consider the user input before proceeding (if not empty).
 
 **Prerequisites:** `research.md` complete
 
-1. **Extract entities from feature spec** → `data-model.md`:
-   - Entity name, fields, relationships
-   - Validation rules from requirements
-   - State transitions if applicable
+0. **Validate Design against UX Reference**:
+    - Check if the proposed architecture supports the latency, interactivity, and flow defined in `ux_reference.md`.
+    - **Linkage**: Ensure key UI states from `ux_reference.md` map to Component Contracts (`@UX_STATE`).
+    - **CRITICAL**: If the technical plan compromises the UX (e.g. "We can't do real-time validation"), you **MUST STOP** and warn the user.
 
-2. **Define interface contracts** (if project has external interfaces) → `/contracts/`:
-   - Identify what interfaces the project exposes to users or other systems
-   - Document the contract format appropriate for the project type
-   - Examples: public APIs for libraries, command schemas for CLI tools, endpoints for web services, grammars for parsers, UI contracts for applications
-   - Skip if project is purely internal (build scripts, one-off tools, etc.)
+1. **Extract entities from feature spec** → `data-model.md`:
+    - Entity name, fields, relationships, validation rules.
+
+2. **Design & Verify Contracts (Semantic Protocol)**:
+    - **Drafting**: Define `[DEF:id:Type]` Headers, Contracts, and closing `[/DEF:id:Type]` for all new modules based on `.ai/standards/semantics.md`.
+    - **TIER Classification**: Explicitly assign `@TIER: [CRITICAL|STANDARD|TRIVIAL]` to each module.
+    - **CRITICAL Requirements**: For all CRITICAL modules, define full `@PRE`, `@POST`, and (if UI) `@UX_STATE` contracts. **MUST** also define testing contracts: `@TEST_CONTRACT`, `@TEST_FIXTURE`, `@TEST_EDGE`, and `@TEST_INVARIANT`.
+    - **Self-Review**:
+      - *Completeness*: Do `@PRE`/`@POST` cover edge cases identified in Research? Are test contracts present for CRITICAL?
+      - *Connectivity*: Do `@RELATION` tags form a coherent graph?
+      - *Compliance*: Does syntax match `[DEF:id:Type]` exactly and is it closed with `[/DEF:id:Type]`?
+    - **Output**: Write verified contracts to `contracts/modules.md`.
+
+3. **Simulate Contract Usage**:
+    - Trace one key user scenario through the defined contracts to ensure data flow continuity.
+    - If a contract interface mismatch is found, fix it immediately.
+
+4. **Generate API contracts**:
+    - Output OpenAPI/GraphQL schema to `/contracts/` for backend-frontend sync.
 
 3. **Agent context update**:
    - Run `.specify/scripts/bash/update-agent-context.sh agy`

.agent/workflows/speckit.tasks.md

@@ -24,7 +24,7 @@ You **MUST** consider the user input before proceeding (if not empty).
 1. **Setup**: Run `.specify/scripts/bash/check-prerequisites.sh --json` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
 
 2. **Load design documents**: Read from FEATURE_DIR:
-   - **Required**: plan.md (tech stack, libraries, structure), spec.md (user stories with priorities)
+   - **Required**: plan.md (tech stack, libraries, structure), spec.md (user stories with priorities), ux_reference.md (experience source of truth)
    - **Optional**: data-model.md (entities), contracts/ (interface contracts), research.md (decisions), quickstart.md (test scenarios)
    - Note: Not all projects have all documents. Generate tasks based on what's available.
 
@@ -70,6 +70,12 @@ The tasks.md should be immediately executable - each task must be specific enoug
 
 **Tests are OPTIONAL**: Only generate test tasks if explicitly requested in the feature specification or if user requests TDD approach.
 
+### UX Preservation (CRITICAL)
+
+- **Source of Truth**: `ux_reference.md` is the absolute standard for the "feel" of the feature.
+- **Violation Warning**: If any task would inherently violate the UX (e.g. "Remove progress bar to simplify code"), you **MUST** flag this to the user immediately.
+- **Verification Task**: You **MUST** add a specific task at the end of each User Story phase: `- [ ] Txxx [USx] Verify implementation matches ux_reference.md (Happy Path & Errors)`
+
 ### Checklist Format (REQUIRED)
 
 Every task MUST strictly follow this format:
@@ -113,9 +119,12 @@ Every task MUST strictly follow this format:
      - If tests requested: Tests specific to that story
    - Mark story dependencies (most stories should be independent)
 
-2. **From Contracts**:
-   - Map each interface contract → to the user story it serves
-   - If tests requested: Each interface contract → contract test task [P] before implementation in that story's phase
+2. **From Contracts (CRITICAL TIER)**:
+    - Identify components marked as `@TIER: CRITICAL` in `contracts/modules.md`.
+    - For these components, **MUST** append the summary of `@PRE`, `@POST`, `@UX_STATE`, and test contracts (`@TEST_FIXTURE`, `@TEST_EDGE`) directly to the task description.
+    - Example: `- [ ] T005 [P] [US1] Implement Auth (CRITICAL: PRE: token exists, POST: returns User, TESTS: 2 edges) in src/auth.py`
+    - Map each contract/endpoint → to the user story it serves
+    - If tests requested: Each contract → contract test task [P] before implementation in that story's phase
 
 3. **From Data Model**:
    - Map each entity to the user story(ies) that need it

.agent/workflows/speckit.test.md

@@ -249,6 +249,7 @@ component/__tests__/Component.test.js
 # [DEF:__tests__/test_module:Module]
 # @RELATION: VERIFIES -> ../module.py
 # @PURPOSE: Contract testing for module
+# [/DEF:__tests__/test_module:Module]
 ```
 
 ---

.ai/PERSONA.md

@@ -26,7 +26,7 @@
 4. **ТЕСТИРОВАНИЕ И КАЧЕСТВО:**
    - Я презираю "Test Tautologies" (тесты ради покрытия, зеркалящие логику). 
    - Тесты должны быть Contract-Driven. Если есть `@PRE`, я ожидаю тест на его нарушение.
-   - Тесты обязаны использовать `@TEST_DATA` из контрактов.
+   - Тесты обязаны использовать `@TEST_` из контрактов.
 
 5. **ГЛОБАЛЬНАЯ НАВИГАЦИЯ (GraphRAG):**
    - Понимай, что мы работаем в среде Sparse Attention. 

.ai/shots/critical_module.py

@@ -3,14 +3,29 @@
 # @SEMANTICS: Finance, ACID, Transfer, Ledger
 # @PURPOSE: Core banking transaction processor with ACID guarantees.
 # @LAYER: Domain (Core)
-# @RELATION: DEPENDS_ON -> [DEF:Infra:PostgresDB]
-# @RELATION: DEPENDS_ON -> [DEF:Infra:AuditLog]
+# @RELATION: DEPENDS_ON ->[DEF:Infra:PostgresDB]
+#
 # @INVARIANT: Total system balance must remain constant (Double-Entry Bookkeeping).
 # @INVARIANT: Negative transfers are strictly forbidden.
 
-# @TEST_DATA: sufficient_funds -> {"from": "acc_A", "to": "acc_B", "amt": 100.00}
-# @TEST_DATA: insufficient_funds -> {"from": "acc_empty", "to": "acc_B", "amt": 1000.00}
-# @TEST_DATA: concurrency_lock -> {./fixtures/transactions.json#race_condition}
+# --- Test Specifications (The "What" and "Why", not the "Data") ---
+# @TEST_CONTRACT: Input -> TransferInputDTO, Output -> TransferResultDTO
+
+# Happy Path
+# @TEST_SCENARIO: sufficient_funds -> Returns COMPLETED, balances updated.
+# @TEST_FIXTURE: sufficient_funds -> file:./__tests__/fixtures/transfers.json#happy_path
+
+# Edge Cases (CRITICAL)
+# @TEST_SCENARIO: insufficient_funds -> Throws BusinessRuleViolation("INSUFFICIENT_FUNDS").
+# @TEST_SCENARIO: negative_amount -> Throws BusinessRuleViolation("Transfer amount must be positive.").
+# @TEST_SCENARIO: self_transfer -> Throws BusinessRuleViolation("Cannot transfer to self.").
+# @TEST_SCENARIO: audit_failure -> Throws RuntimeError("TRANSACTION_ABORTED").
+# @TEST_SCENARIO: concurrency_conflict -> Throws DBTransactionError.
+
+# Linking Tests to Invariants
+# @TEST_INVARIANT: total_balance_constant -> VERIFIED_BY: [sufficient_funds, concurrency_conflict]
+# @TEST_INVARIANT: negative_transfer_forbidden -> VERIFIED_BY: [negative_amount]
+
 
 from decimal import Decimal
 from typing import NamedTuple

.ai/shots/frontend_component.svelte

@@ -1,24 +1,67 @@
 <!-- [DEF:FrontendComponentShot:Component] -->
-<!-- /**
-   * @TIER: CRITICAL
-   * @SEMANTICS: Task, Button, Action, UX
-   * @PURPOSE: Action button to spawn a new task with full UX feedback cycle.
-   * @LAYER: UI (Presentation)
-   * @RELATION: CALLS -> postApi
-   * @INVARIANT: Must prevent double-submission while loading.
-   * 
-   * @TEST_DATA: idle_state -> {"isLoading": false}
-   * @TEST_DATA: loading_state -> {"isLoading": true}
-   * 
-   * @UX_STATE: Idle -> Button enabled, primary color.
-   * @UX_STATE: Loading -> Button disabled, spinner visible.
-   * @UX_STATE: Error -> Toast notification triggers.
-   * 
-   * @UX_FEEDBACK: Toast success/error.
-   * @UX_TEST: Idle -> {click: spawnTask, expected: isLoading=true}
-   * @UX_TEST: Success -> {api_resolve: 200, expected: toast.success called}
-   */
-   -->
+<!--
+/**
+ * @TIER: CRITICAL
+ * @SEMANTICS: Task, Button, Action, UX
+ * @PURPOSE: Action button to spawn a new task with full UX feedback cycle.
+ * @LAYER: UI (Presentation)
+ * @RELATION: CALLS -> postApi
+ *
+ * @INVARIANT: Must prevent double-submission while loading.
+ * @INVARIANT: Loading state must always terminate (no infinite spinner).
+ * @INVARIANT: User must receive feedback on both success and failure.
+ *
+ * @TEST_CONTRACT: ComponentState ->
+ * {
+ *   required_fields: {
+ *     isLoading: bool
+ *   },
+ *   invariants: [
+ *     "isLoading=true implies button.disabled=true",
+ *     "isLoading=true implies aria-busy=true",
+ *     "isLoading=true implies spinner visible"
+ *   ]
+ * }
+ *
+ * @TEST_CONTRACT: ApiResponse ->
+ * {
+ *   required_fields: {},
+ *   optional_fields: {
+ *     task_id: str
+ *   }
+ * }
+
+ * @TEST_FIXTURE: idle_state ->
+ * {
+ *   isLoading: false
+ * }
+ *
+ * @TEST_FIXTURE: successful_response ->
+ * {
+ *   task_id: "task_123"
+ * }
+ 
+ * @TEST_EDGE: api_failure -> raises Error("Network")
+ * @TEST_EDGE: empty_response -> {}
+ * @TEST_EDGE: rapid_double_click -> special: concurrent_click
+ * @TEST_EDGE: unresolved_promise -> special: pending_state
+ 
+ * @TEST_INVARIANT: prevent_double_submission -> verifies: [rapid_double_click]
+ * @TEST_INVARIANT: loading_state_consistency -> verifies: [idle_state, pending_state]
+ * @TEST_INVARIANT: feedback_always_emitted -> verifies: [successful_response, api_failure]
+
+ * @UX_STATE: Idle -> Button enabled, primary color, no spinner.
+ * @UX_STATE: Loading -> Button disabled, spinner visible, aria-busy=true.
+ * @UX_STATE: Success -> Toast success displayed.
+ * @UX_STATE: Error -> Toast error displayed.
+ *
+ * @UX_FEEDBACK: toast.success, toast.error
+ *
+ * @UX_TEST: Idle -> {click: spawnTask, expected: isLoading=true}
+ * @UX_TEST: Loading -> {double_click: ignored, expected: single_api_call}
+ * @UX_TEST: Success -> {api_resolve: task_id, expected: toast.success called}
+ * @UX_TEST: Error -> {api_reject: error, expected: toast.error called} 
+-->
 <script>
   import { postApi } from "$lib/api.js";
   import { t } from "$lib/i18n";

.ai/standards/semantics.md

@@ -5,6 +5,7 @@
 
 #### I. ЗАКОН (АКСИОМЫ)
 1. Смысл первичен. Код вторичен.
+2.Слепота недопустима. Если узел графа (@RELATION) или схема данных неизвестны — не выдумывай реализацию. Остановись и запроси контекст.
 2. Контракт (@PRE/@POST) — источник истины.
 **3. UX — это логика, а не декор. Состояния интерфейса — часть контракта.**
 4. Структура `[DEF]...[/DEF]` — нерушима.
@@ -47,11 +48,13 @@
   @PRE: Входные условия.
   @POST: Гарантии выхода.
   @SIDE_EFFECT: Мутации, IO.
+  @DATA_CONTRACT: Ссылка на DTO/Pydantic модель. Заменяет ручное описание @PARAM. Формат: Input -> [Model], Output -> [Model].
   
 **UX Теги (Svelte/Frontend):**
   **@UX_STATE:** `[StateName] -> Визуальное поведение` (Idle, Loading, Error).
   **@UX_FEEDBACK:** Реакция системы (Toast, Shake, Red Border).
   **@UX_RECOVERY:** Механизм исправления ошибки пользователем (Retry, Clear Input).
+  **@UX_REATIVITY:** Явное указание использования рун. Формат: State: $state, Derived: $derived. Никаких устаревших export let.
   
 **UX Testing Tags (для Tester Agent):**
   **@UX_TEST:** Спецификация теста для UX состояния.
@@ -63,41 +66,26 @@
 #### V. АДАПТАЦИЯ (TIERS)
 Определяется тегом `@TIER` в Header.
 
-1. **CRITICAL** (Core/Security/**Complex UI**):
-   - Требование: Полный контракт (включая **все @UX теги**), Граф, Инварианты, Строгие Логи.
-   ```
-   @TEST_CONTRACT: Обязательное описание структуры входных/выходных данных.
-   Формат:
-   @TEST_CONTRACT: Name -> {
-      required_fields: {field: type},
-      optional_fields: {field: type},
-      invariants: [...]
-   }
+### V. УРОВНИ СТРОГОСТИ (TIERS)
+Степень контроля задается тегом `@TIER` в Header.
 
-   @TEST_FIXTURE: Эталонный корректный пример (happy-path).
-   Формат:
-   @TEST_FIXTURE: fixture_name -> {INLINE_JSON | PATH#fragment}
+**1. CRITICAL** (Ядро / Безопасность / Сложный UI)
+- **Закон:** Полный GRACE. Граф, Инварианты, Строгий Лог, все `@UX` теги.
+- **Догма Тестирования:** Тесты рождаются из контракта. Голый код без данных — слеп.
+  - `@TEST_CONTRACT: InputType -> OutputType`. (Строгий интерфейс).
+  - `@TEST_SCENARIO: name -> Ожидаемое поведение`. (Суть теста).
+  - `@TEST_FIXTURE: name -> file:PATH | INLINE_JSON`. (Данные для Happy Path).
+  - `@TEST_EDGE: name -> Описание сбоя`. (Минимум 3 границы). 
+    - *Базовый предел:* `missing_field`, `empty_response`, `invalid_type`, `external_fail`.
+  - `@TEST_INVARIANT: inv_name -> VERIFIED_BY: [scenario_1, ...]`. (Смыкание логики).
+- **Исполнение:** Tester Agent обязан строить проверки строго по этим тегам.
 
-   @TEST_EDGE: Граничные случаи (минимум 3 для CRITICAL).
-   Формат:
-   @TEST_EDGE: case_name -> {INLINE_JSON | special_case}
+**2. STANDARD** (Бизнес-логика / Формы)
+- **Закон:** База. (`@PURPOSE`, `@UX_STATE`, Лог, `@RELATION`).
+- **Исключение:** Для сложных форм внедряй `@TEST_SCENARIO` и `@TEST_INVARIANT`.
 
-   @TEST_INVARIANT: Обязательно. Связывает тесты с инвариантами.
-   Формат:
-   @TEST_INVARIANT: invariant_name -> verifies: [test_case_1, test_case_2]
-
-   Обязательные edge-типы для CRITICAL:
-   - missing_required_field
-   - empty_response
-   - invalid_type
-   - external_failure (exception)
-   ```
-   - Tester Agent **ОБЯЗАН** использовать @TEST_CONTRACT, @TEST_FIXTURE и @TEST_EDGE при написании тестов для CRITICAL модулей.
-2. **STANDARD** (BizLogic/**Forms**):
-   - Требование: Базовый контракт (@PURPOSE, @UX_STATE), Логи, @RELATION.
-   - @TEST_DATA: Рекомендуется для Complex Forms.
-3. **TRIVIAL** (DTO/**Atoms**):
-   - Требование: Только Якоря [DEF] и @PURPOSE.
+**3. TRIVIAL** (DTO / Атомы UI / Утилиты)
+- **Закон:** Каркас. Только якорь `[DEF]` и `@PURPOSE`. Данные и графы не требуются.
 
 #### VI. ЛОГИРОВАНИЕ (ДАО МОЛЕКУЛЫ / MOLECULAR TOPOLOGY)
 Цель: Трассировка. Самокоррекция. Управление Матрицей Внимания ("Химия мышления").
@@ -129,10 +117,16 @@
 
 **Незыблемое правило:** Всякому логу системы — тавро `source`. Для Внешенго Мира (Svelte) начертай рунами вручную: `console.log("[ID][REFLECT] Msg")`.
 
-#### VII. АЛГОРИТМ ГЕНЕРАЦИИ
-1. АНАЛИЗ. Оцени TIER, слой и UX-требования.
+#### VIII. АЛГОРИТМ ГЕНЕРАЦИИ И ВЫХОД ИЗ ТУПИКА
+1. АНАЛИЗ. Оцени TIER, слой и UX-требования. Чего не хватает? Запроси `[NEED_CONTEXT: id]`.
 2. КАРКАС. Создай `[DEF]`, Header и Контракты.
-3. РЕАЛИЗАЦИЯ. Напиши логику, удовлетворяющую Контракту (и UX-состояниям).
+3. РЕАЛИЗАЦИЯ. Напиши логику, удовлетворяющую Контракту (и UX-состояниям). Орошай путь логами `[REASON]` и `[REFLECT]`.
 4. ЗАМЫКАНИЕ. Закрой все `[/DEF]`.
 
+**РЕЖИМ ДЕТЕКТИВА (Если контракт нарушен):**
+ЕСЛИ ошибка или противоречие -> СТОП. 
+1. Выведи `[COHERENCE_CHECK_FAILED]`.
+2. Сформулируй гипотезу: `[EXPLORE] Ошибка в I/O, состоянии или зависимости?`
+3. Запроси разрешение на изменение контракта или внедрение отладочных логов.
+
 ЕСЛИ ошибка или противоречие -> СТОП. Выведи `[COHERENCE_CHECK_FAILED]`.

.codex/prompts/audit-test.md

@@ -6,7 +6,7 @@ description: Audit AI-generated unit tests. Your goal is to aggressively search
 **OBJECTIVE:** Audit AI-generated unit tests. Your goal is to aggressively search for "Test Tautologies", "Logic Echoing", and "Contract Negligence". You are the final gatekeeper. If a test is meaningless, you MUST reject it.
 
 **INPUT:**
-1. SOURCE CODE (with GRACE-Poly `[DEF]` Contract: `@PRE`, `@POST`, `@TEST_DATA`).
+1. SOURCE CODE (with GRACE-Poly `[DEF]` Contract: `@PRE`, `@POST`, `@TEST_CONTRACT`, `@TEST_FIXTURE`, `@TEST_EDGE`, `@TEST_INVARIANT`).
 2. GENERATED TEST CODE.
 
 ### I. CRITICAL ANTI-PATTERNS (REJECT IMMEDIATELY IF FOUND):
@@ -17,7 +17,7 @@ description: Audit AI-generated unit tests. Your goal is to aggressively search
 
 2. **The Logic Mirror (Echoing):**
    - *Definition:* The test re-implements the exact same algorithmic logic found in the source code to calculate the `expected_result`. If the original logic is flawed, the test will falsely pass.
-   - *Rule:* Tests must assert against **static, predefined outcomes** (from `@TEST_DATA` or explicit constants), NOT dynamically calculated outcomes using the same logic as the source.
+   - *Rule:* Tests must assert against **static, predefined outcomes** (from `@TEST_FIXTURE`, `@TEST_EDGE`, `@TEST_INVARIANT` or explicit constants), NOT dynamically calculated outcomes using the same logic as the source.
 
 3. **The "Happy Path" Illusion:**
    - *Definition:* The test suite only checks successful executions but ignores the `@PRE` conditions (Negative Testing).
@@ -26,26 +26,78 @@ description: Audit AI-generated unit tests. Your goal is to aggressively search
 4. **Missing Post-Condition Verification:**
    - *Definition:* The test calls the function but only checks the return value, ignoring `@SIDE_EFFECT` or `@POST` state changes (e.g., failing to verify that a DB call was made or a Store was updated).
 
-### II. AUDIT CHECKLIST
+5. **Missing Edge Case Coverage:**
+   - *Definition:* The test suite ignores `@TEST_EDGE` scenarios defined in the contract.
+   - *Rule:* Every `@TEST_EDGE` in the source contract MUST have a corresponding test case.
+
+6. **Missing Invariant Verification:**
+   - *Definition:* The test suite does not verify `@TEST_INVARIANT` conditions.
+   - *Rule:* Every `@TEST_INVARIANT` MUST be verified by at least one test that attempts to break it.
+
+7. **Missing UX State Testing (Svelte Components):**
+   - *Definition:* For Svelte components with `@UX_STATE`, the test suite does not verify state transitions.
+   - *Rule:* Every `@UX_STATE` transition MUST have a test verifying the visual/behavioral change.
+   - *Check:* `@UX_FEEDBACK` mechanisms (toast, shake, color) must be tested.
+   - *Check:* `@UX_RECOVERY` mechanisms (retry, clear input) must be tested.
+
+### II. SEMANTIC PROTOCOL COMPLIANCE
+
+Verify the test file follows GRACE-Poly semantics:
+
+1. **Anchor Integrity:**
+   - Test file MUST start with `[DEF:__tests__/test_name:Module]`
+   - Test file MUST end with `[/DEF:__tests__/test_name:Module]`
+
+2. **Required Tags:**
+   - `@RELATION: VERIFIES -> <path_to_source>` must be present
+   - `@PURPOSE:` must describe what is being tested
+
+3. **TIER Alignment:**
+   - If source is `@TIER: CRITICAL`, test MUST cover all `@TEST_CONTRACT`, `@TEST_FIXTURE`, `@TEST_EDGE`, `@TEST_INVARIANT`
+   - If source is `@TIER: STANDARD`, test MUST cover `@PRE` and `@POST`
+   - If source is `@TIER: TRIVIAL`, basic smoke test is acceptable
+
+### III. AUDIT CHECKLIST
 
 Evaluate the test code against these criteria:
 1. **Target Invocation:** Does the test actually import and call the function/component declared in the `@RELATION: VERIFIES` tag?
 2. **Contract Alignment:** Does the test suite cover 100% of the `@PRE` (negative tests) and `@POST` (assertions) conditions from the source contract?
-3. **Data Usage:** Does the test use the exact scenarios defined in `@TEST_DATA`?
-4. **Mocking Sanity:** Are external dependencies mocked correctly WITHOUT mocking the system under test itself?
+3. **Test Contract Compliance:** Does the test follow the interface defined in `@TEST_CONTRACT`?
+4. **Data Usage:** Does the test use the exact scenarios defined in `@TEST_FIXTURE`?
+5. **Edge Coverage:** Are all `@TEST_EDGE` scenarios tested?
+6. **Invariant Coverage:** Are all `@TEST_INVARIANT` conditions verified?
+7. **UX Coverage (if applicable):** Are all `@UX_STATE`, `@UX_FEEDBACK`, `@UX_RECOVERY` tested?
+8. **Mocking Sanity:** Are external dependencies mocked correctly WITHOUT mocking the system under test itself?
+9. **Semantic Anchor:** Does the test file have proper `[DEF]` and `[/DEF]` anchors?
 
-### III. OUTPUT FORMAT
+### IV. OUTPUT FORMAT
 
 You MUST respond strictly in the following JSON format. Do not add markdown blocks outside the JSON.
 
 {
   "verdict": "APPROVED" | "REJECTED",
-  "rejection_reason": "TAUTOLOGY" | "LOGIC_MIRROR" | "WEAK_CONTRACT_COVERAGE" | "OVER_MOCKED" | "NONE",
+  "rejection_reason": "TAUTOLOGY" | "LOGIC_MIRROR" | "WEAK_CONTRACT_COVERAGE" | "OVER_MOCKED" | "MISSING_EDGES" | "MISSING_INVARIANTS" | "MISSING_UX_TESTS" | "SEMANTIC_VIOLATION" | "NONE",
   "audit_details": {
     "target_invoked": true/false,
     "pre_conditions_tested": true/false,
     "post_conditions_tested": true/false,
-    "test_data_used": true/false
+    "test_fixture_used": true/false,
+    "edges_covered": true/false,
+    "invariants_verified": true/false,
+    "ux_states_tested": true/false,
+    "semantic_anchors_present": true/false
+  },
+  "coverage_summary": {
+    "total_edges": number,
+    "edges_tested": number,
+    "total_invariants": number,
+    "invariants_tested": number,
+    "total_ux_states": number,
+    "ux_states_tested": number
+  },
+  "tier_compliance": {
+    "source_tier": "CRITICAL" | "STANDARD" | "TRIVIAL",
+    "meets_tier_requirements": true/false
   },
   "feedback": "Strict, actionable feedback for the test generator agent. Explain exactly which anti-pattern was detected and how to fix it."
 }

.codex/prompts/read_semantic.md

@@ -1,4 +1,4 @@
 ---
 description: USE SEMANTIC
 ---
-Прочитай .specify/memory/semantics.md (или .ai/standards/semantics.md, если не найден). ОБЯЗАТЕЛЬНО используй его при разработке
+Прочитай .ai/standards/semantics.md. ОБЯЗАТЕЛЬНО используй его при разработке

.codex/prompts/speckit.analyze.md

@@ -63,6 +63,7 @@ Load only the minimal necessary context from each artifact:
 **From constitution:**
 
 - Load `.ai/standards/constitution.md` for principle validation
+    - Load `.ai/standards/semantics.md` for technical standard validation
 
 ### 3. Build Semantic Models
 

.codex/prompts/speckit.fix.md

@@ -20,7 +20,7 @@ Analyze test failure reports, identify root causes, and fix implementation issue
 
 1. **USE CODER MODE**: Always switch to `coder` mode for code fixes
 2. **SEMANTIC PROTOCOL**: Never remove semantic annotations ([DEF], @TAGS). Only update code logic.
-3. **TEST DATA**: If tests use @TEST_DATA fixtures, preserve them when fixing
+3. **TEST DATA**: If tests use @TEST_ fixtures, preserve them when fixing
 4. **NO DELETION**: Never delete existing tests or semantic annotations
 5. **REPORT FIRST**: Always write a fix report before making changes
 

.codex/prompts/speckit.implement.md

@@ -53,6 +53,15 @@ You **MUST** consider the user input before proceeding (if not empty).
    - **IF EXISTS**: Read research.md for technical decisions and constraints
    - **IF EXISTS**: Read quickstart.md for integration scenarios
 
+3. Load and analyze the implementation context:
+    - **REQUIRED**: Read `.ai/standards/semantics.md` for strict coding standards and contract requirements
+    - **REQUIRED**: Read tasks.md for the complete task list and execution plan
+    - **REQUIRED**: Read plan.md for tech stack, architecture, and file structure
+    - **IF EXISTS**: Read data-model.md for entities and relationships
+    - **IF EXISTS**: Read contracts/ for API specifications and test requirements
+    - **IF EXISTS**: Read research.md for technical decisions and constraints
+    - **IF EXISTS**: Read quickstart.md for integration scenarios
+
 4. **Project Setup Verification**:
    - **REQUIRED**: Create/verify ignore files based on actual project setup:
 
@@ -111,7 +120,13 @@ You **MUST** consider the user input before proceeding (if not empty).
    - **Validation checkpoints**: Verify each phase completion before proceeding
 
 7. Implementation execution rules:
-   - **Setup first**: Initialize project structure, dependencies, configuration
+    - **Strict Adherence**: Apply `.ai/standards/semantics.md` rules:
+      - Every file MUST start with a `[DEF:id:Type]` header and end with a closing `[/DEF:id:Type]` anchor.
+      - Include `@TIER` and define contracts (`@PRE`, `@POST`).
+      - For Svelte components, use `@UX_STATE`, `@UX_FEEDBACK`, `@UX_RECOVERY`, and explicitly declare reactivity with `@UX_REATIVITY: State: $state, Derived: $derived`.
+      - **Molecular Topology Logging**: Use prefixes `[EXPLORE]`, `[REASON]`, `[REFLECT]` in logs to trace logic.
+    - **CRITICAL Contracts**: If a task description contains a contract summary (e.g., `CRITICAL: PRE: ..., POST: ...`), these constraints are **MANDATORY** and must be strictly implemented in the code using guards/assertions (if applicable per protocol).
+    - **Setup first**: Initialize project structure, dependencies, configuration
    - **Tests before code**: If you need to write tests for contracts, entities, and integration scenarios
    - **Core development**: Implement models, services, CLI commands, endpoints
    - **Integration work**: Database connections, middleware, logging, external services

.codex/prompts/speckit.plan.md

@@ -22,7 +22,7 @@ You **MUST** consider the user input before proceeding (if not empty).
 
 1. **Setup**: Run `.specify/scripts/bash/setup-plan.sh --json` from repo root and parse JSON for FEATURE_SPEC, IMPL_PLAN, SPECS_DIR, BRANCH. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
 
-2. **Load context**: Read FEATURE_SPEC and `.ai/standards/constitution.md`. Load IMPL_PLAN template (already copied).
+2. **Load context**: Read `.ai/ROOT.md` and `.ai/PROJECT_MAP.md` to understand the project structure and navigation. Then read required standards: `.ai/standards/constitution.md` and `.ai/standards/semantics.md`. Load IMPL_PLAN template.
 
 3. **Execute plan workflow**: Follow the structure in IMPL_PLAN template to:
    - Fill Technical Context (mark unknowns as "NEEDS CLARIFICATION")
@@ -64,16 +64,30 @@ You **MUST** consider the user input before proceeding (if not empty).
 
 **Prerequisites:** `research.md` complete
 
-1. **Extract entities from feature spec** → `data-model.md`:
-   - Entity name, fields, relationships
-   - Validation rules from requirements
-   - State transitions if applicable
+0. **Validate Design against UX Reference**:
+    - Check if the proposed architecture supports the latency, interactivity, and flow defined in `ux_reference.md`.
+    - **Linkage**: Ensure key UI states from `ux_reference.md` map to Component Contracts (`@UX_STATE`).
+    - **CRITICAL**: If the technical plan compromises the UX (e.g. "We can't do real-time validation"), you **MUST STOP** and warn the user.
 
-2. **Define interface contracts** (if project has external interfaces) → `/contracts/`:
-   - Identify what interfaces the project exposes to users or other systems
-   - Document the contract format appropriate for the project type
-   - Examples: public APIs for libraries, command schemas for CLI tools, endpoints for web services, grammars for parsers, UI contracts for applications
-   - Skip if project is purely internal (build scripts, one-off tools, etc.)
+1. **Extract entities from feature spec** → `data-model.md`:
+    - Entity name, fields, relationships, validation rules.
+
+2. **Design & Verify Contracts (Semantic Protocol)**:
+    - **Drafting**: Define `[DEF:id:Type]` Headers, Contracts, and closing `[/DEF:id:Type]` for all new modules based on `.ai/standards/semantics.md`.
+    - **TIER Classification**: Explicitly assign `@TIER: [CRITICAL|STANDARD|TRIVIAL]` to each module.
+    - **CRITICAL Requirements**: For all CRITICAL modules, define full `@PRE`, `@POST`, and (if UI) `@UX_STATE` contracts. **MUST** also define testing contracts: `@TEST_CONTRACT`, `@TEST_FIXTURE`, `@TEST_EDGE`, and `@TEST_INVARIANT`.
+    - **Self-Review**:
+      - *Completeness*: Do `@PRE`/`@POST` cover edge cases identified in Research? Are test contracts present for CRITICAL?
+      - *Connectivity*: Do `@RELATION` tags form a coherent graph?
+      - *Compliance*: Does syntax match `[DEF:id:Type]` exactly and is it closed with `[/DEF:id:Type]`?
+    - **Output**: Write verified contracts to `contracts/modules.md`.
+
+3. **Simulate Contract Usage**:
+    - Trace one key user scenario through the defined contracts to ensure data flow continuity.
+    - If a contract interface mismatch is found, fix it immediately.
+
+4. **Generate API contracts**:
+    - Output OpenAPI/GraphQL schema to `/contracts/` for backend-frontend sync.
 
 3. **Agent context update**:
    - Run `.specify/scripts/bash/update-agent-context.sh agy`

.codex/prompts/speckit.tasks.md

@@ -24,7 +24,7 @@ You **MUST** consider the user input before proceeding (if not empty).
 1. **Setup**: Run `.specify/scripts/bash/check-prerequisites.sh --json` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
 
 2. **Load design documents**: Read from FEATURE_DIR:
-   - **Required**: plan.md (tech stack, libraries, structure), spec.md (user stories with priorities)
+   - **Required**: plan.md (tech stack, libraries, structure), spec.md (user stories with priorities), ux_reference.md (experience source of truth)
    - **Optional**: data-model.md (entities), contracts/ (interface contracts), research.md (decisions), quickstart.md (test scenarios)
    - Note: Not all projects have all documents. Generate tasks based on what's available.
 
@@ -70,6 +70,12 @@ The tasks.md should be immediately executable - each task must be specific enoug
 
 **Tests are OPTIONAL**: Only generate test tasks if explicitly requested in the feature specification or if user requests TDD approach.
 
+### UX Preservation (CRITICAL)
+
+- **Source of Truth**: `ux_reference.md` is the absolute standard for the "feel" of the feature.
+- **Violation Warning**: If any task would inherently violate the UX (e.g. "Remove progress bar to simplify code"), you **MUST** flag this to the user immediately.
+- **Verification Task**: You **MUST** add a specific task at the end of each User Story phase: `- [ ] Txxx [USx] Verify implementation matches ux_reference.md (Happy Path & Errors)`
+
 ### Checklist Format (REQUIRED)
 
 Every task MUST strictly follow this format:
@@ -113,9 +119,12 @@ Every task MUST strictly follow this format:
      - If tests requested: Tests specific to that story
    - Mark story dependencies (most stories should be independent)
 
-2. **From Contracts**:
-   - Map each interface contract → to the user story it serves
-   - If tests requested: Each interface contract → contract test task [P] before implementation in that story's phase
+2. **From Contracts (CRITICAL TIER)**:
+    - Identify components marked as `@TIER: CRITICAL` in `contracts/modules.md`.
+    - For these components, **MUST** append the summary of `@PRE`, `@POST`, `@UX_STATE`, and test contracts (`@TEST_FIXTURE`, `@TEST_EDGE`) directly to the task description.
+    - Example: `- [ ] T005 [P] [US1] Implement Auth (CRITICAL: PRE: token exists, POST: returns User, TESTS: 2 edges) in src/auth.py`
+    - Map each contract/endpoint → to the user story it serves
+    - If tests requested: Each contract → contract test task [P] before implementation in that story's phase
 
 3. **From Data Model**:
    - Map each entity to the user story(ies) that need it

.codex/prompts/speckit.test.md

@@ -20,7 +20,7 @@ Execute full testing cycle: analyze code for testable modules, write tests with
 
 1. **NEVER delete existing tests** - Only update if they fail due to bugs in the test or implementation
 2. **NEVER duplicate tests** - Check existing tests first before creating new ones
-3. **Use TEST_DATA fixtures** - For CRITICAL tier modules, read @TEST_DATA from .specify/memory/semantics.md
+3. **Use TEST_FIXTURE fixtures** - For CRITICAL tier modules, read @TEST_FIXTURE from semantics header
 4. **Co-location required** - Write tests in `__tests__` directories relative to the code being tested
 
 ## Execution Steps
@@ -40,9 +40,9 @@ Determine:
 - Identify completed implementation tasks (not test tasks)
 - Extract file paths that need tests
 
-**From .specify/memory/semantics.md:**
+**From .ai/standards/semantics.md:**
 - Read @TIER annotations for modules
-- For CRITICAL modules: Read @TEST_DATA fixtures
+- For CRITICAL modules: Read @TEST_ fixtures
 
 **From existing tests:**
 - Scan `__tests__` directories for existing tests
@@ -52,8 +52,8 @@ Determine:
 
 Create coverage matrix:
 
-| Module | File | Has Tests | TIER | TEST_DATA Available |
-|--------|------|-----------|------|-------------------|
+| Module | File | Has Tests | TIER | TEST_FIXTURE Available |
+|--------|------|-----------|------|----------------------|
 | ... | ... | ... | ... | ... |
 
 ### 4. Write Tests (TDD Approach)
@@ -61,7 +61,7 @@ Create coverage matrix:
 For each module requiring tests:
 
 1. **Check existing tests**: Scan `__tests__/` for duplicates
-2. **Read TEST_DATA**: If CRITICAL tier, read @TEST_DATA from .specify/memory/semantics.md
+2. **Read TEST_FIXTURE**: If CRITICAL tier, read @TEST_FIXTURE from semantic header
 3. **Write test**: Follow co-location strategy
    - Python: `src/module/__tests__/test_module.py`
    - Svelte: `src/lib/components/__tests__/test_component.test.js`
@@ -102,6 +102,7 @@ describe('Component UX States', () => {
   // @UX_RECOVERY: Retry on error
   it('should allow retry on error', async () => { ... });
 });
+// [/DEF:__tests__/test_Component:Module]
 ```
 
 ### 5. Test Documentation
@@ -170,7 +171,7 @@ Generate test execution report:
 
 - [ ] Fix failed tests
 - [ ] Add more coverage for [module]
-- [ ] Review TEST_DATA fixtures
+- [ ] Review TEST_FIXTURE fixtures
 ```
 
 ## Context for Testing

.kilocode/rules/specify-rules.md

@@ -45,6 +45,8 @@ Auto-generated from all feature plans. Last updated: 2025-12-19
 - SQLite task/result persistence (existing task DB), filesystem only for existing artifacts (no new primary store required) (020-task-reports-design)
 - Node.js 18+ runtime, SvelteKit (existing frontend stack) + SvelteKit, Tailwind CSS, existing frontend UI primitives under `frontend/src/lib/components/ui` (001-unify-frontend-style)
 - N/A (UI styling and component behavior only) (001-unify-frontend-style)
+- Python 3.9+ (backend scripts/services), Shell (release tooling) + FastAPI stack (existing backend), ConfigManager, TaskManager, файловые утилиты, internal artifact registries (020-clean-repo-enterprise)
+- PostgreSQL (конфигурации/метаданные), filesystem (артефакты дистрибутива, отчёты проверки) (020-clean-repo-enterprise)
 
 - Python 3.9+ (Backend), Node.js 18+ (Frontend Build) (001-plugin-arch-svelte-ui)
 
@@ -65,9 +67,9 @@ cd src; pytest; ruff check .
 Python 3.9+ (Backend), Node.js 18+ (Frontend Build): Follow standard conventions
 
 ## Recent Changes
+- 020-clean-repo-enterprise: Added Python 3.9+ (backend scripts/services), Shell (release tooling) + FastAPI stack (existing backend), ConfigManager, TaskManager, файловые утилиты, internal artifact registries
 - 001-unify-frontend-style: Added Node.js 18+ runtime, SvelteKit (existing frontend stack) + SvelteKit, Tailwind CSS, existing frontend UI primitives under `frontend/src/lib/components/ui`
 - 020-task-reports-design: Added Python 3.9+ (backend), Node.js 18+ (frontend) + FastAPI, SvelteKit, Tailwind CSS, SQLAlchemy/Pydantic task models, existing task/websocket stack
-- 019-superset-ux-redesign: Added Python 3.9+ (Backend), Node.js 18+ (Frontend) + FastAPI, SvelteKit, Tailwind CSS, SQLAlchemy, WebSocket (existing)
 
 
 <!-- MANUAL ADDITIONS START -->

.kilocode/workflows/audit-test.md

@@ -0,0 +1,103 @@
+---
+description: Audit AI-generated unit tests. Your goal is to aggressively search for "Test Tautologies", "Logic Echoing", and "Contract Negligence". You are the final gatekeeper. If a test is meaningless, you MUST reject it.
+---
+
+**ROLE:** Elite Quality Assurance Architect and Red Teamer.
+**OBJECTIVE:** Audit AI-generated unit tests. Your goal is to aggressively search for "Test Tautologies", "Logic Echoing", and "Contract Negligence". You are the final gatekeeper. If a test is meaningless, you MUST reject it.
+
+**INPUT:**
+1. SOURCE CODE (with GRACE-Poly `[DEF]` Contract: `@PRE`, `@POST`, `@TEST_CONTRACT`, `@TEST_FIXTURE`, `@TEST_EDGE`, `@TEST_INVARIANT`).
+2. GENERATED TEST CODE.
+
+### I. CRITICAL ANTI-PATTERNS (REJECT IMMEDIATELY IF FOUND):
+
+1. **The Tautology (Self-Fulfilling Prophecy):**
+   - *Definition:* The test asserts hardcoded values against hardcoded values without executing the core business logic, or mocks the actual function being tested.
+   - *Example of Failure:* `assert 2 + 2 == 4` or mocking the class under test so that it returns exactly what the test asserts.
+
+2. **The Logic Mirror (Echoing):**
+   - *Definition:* The test re-implements the exact same algorithmic logic found in the source code to calculate the `expected_result`. If the original logic is flawed, the test will falsely pass.
+   - *Rule:* Tests must assert against **static, predefined outcomes** (from `@TEST_FIXTURE`, `@TEST_EDGE`, `@TEST_INVARIANT` or explicit constants), NOT dynamically calculated outcomes using the same logic as the source.
+
+3. **The "Happy Path" Illusion:**
+   - *Definition:* The test suite only checks successful executions but ignores the `@PRE` conditions (Negative Testing).
+   - *Rule:* Every `@PRE` tag in the source contract MUST have a corresponding test that deliberately violates it and asserts the correct Exception/Error state.
+
+4. **Missing Post-Condition Verification:**
+   - *Definition:* The test calls the function but only checks the return value, ignoring `@SIDE_EFFECT` or `@POST` state changes (e.g., failing to verify that a DB call was made or a Store was updated).
+
+5. **Missing Edge Case Coverage:**
+   - *Definition:* The test suite ignores `@TEST_EDGE` scenarios defined in the contract.
+   - *Rule:* Every `@TEST_EDGE` in the source contract MUST have a corresponding test case.
+
+6. **Missing Invariant Verification:**
+   - *Definition:* The test suite does not verify `@TEST_INVARIANT` conditions.
+   - *Rule:* Every `@TEST_INVARIANT` MUST be verified by at least one test that attempts to break it.
+
+7. **Missing UX State Testing (Svelte Components):**
+   - *Definition:* For Svelte components with `@UX_STATE`, the test suite does not verify state transitions.
+   - *Rule:* Every `@UX_STATE` transition MUST have a test verifying the visual/behavioral change.
+   - *Check:* `@UX_FEEDBACK` mechanisms (toast, shake, color) must be tested.
+   - *Check:* `@UX_RECOVERY` mechanisms (retry, clear input) must be tested.
+
+### II. SEMANTIC PROTOCOL COMPLIANCE
+
+Verify the test file follows GRACE-Poly semantics:
+
+1. **Anchor Integrity:**
+   - Test file MUST start with `[DEF:__tests__/test_name:Module]`
+   - Test file MUST end with `[/DEF:__tests__/test_name:Module]`
+
+2. **Required Tags:**
+   - `@RELATION: VERIFIES -> <path_to_source>` must be present
+   - `@PURPOSE:` must describe what is being tested
+
+3. **TIER Alignment:**
+   - If source is `@TIER: CRITICAL`, test MUST cover all `@TEST_CONTRACT`, `@TEST_FIXTURE`, `@TEST_EDGE`, `@TEST_INVARIANT`
+   - If source is `@TIER: STANDARD`, test MUST cover `@PRE` and `@POST`
+   - If source is `@TIER: TRIVIAL`, basic smoke test is acceptable
+
+### III. AUDIT CHECKLIST
+
+Evaluate the test code against these criteria:
+1. **Target Invocation:** Does the test actually import and call the function/component declared in the `@RELATION: VERIFIES` tag?
+2. **Contract Alignment:** Does the test suite cover 100% of the `@PRE` (negative tests) and `@POST` (assertions) conditions from the source contract?
+3. **Test Contract Compliance:** Does the test follow the interface defined in `@TEST_CONTRACT`?
+4. **Data Usage:** Does the test use the exact scenarios defined in `@TEST_FIXTURE`?
+5. **Edge Coverage:** Are all `@TEST_EDGE` scenarios tested?
+6. **Invariant Coverage:** Are all `@TEST_INVARIANT` conditions verified?
+7. **UX Coverage (if applicable):** Are all `@UX_STATE`, `@UX_FEEDBACK`, `@UX_RECOVERY` tested?
+8. **Mocking Sanity:** Are external dependencies mocked correctly WITHOUT mocking the system under test itself?
+9. **Semantic Anchor:** Does the test file have proper `[DEF]` and `[/DEF]` anchors?
+
+### IV. OUTPUT FORMAT
+
+You MUST respond strictly in the following JSON format. Do not add markdown blocks outside the JSON.
+
+{
+  "verdict": "APPROVED" | "REJECTED",
+  "rejection_reason": "TAUTOLOGY" | "LOGIC_MIRROR" | "WEAK_CONTRACT_COVERAGE" | "OVER_MOCKED" | "MISSING_EDGES" | "MISSING_INVARIANTS" | "MISSING_UX_TESTS" | "SEMANTIC_VIOLATION" | "NONE",
+  "audit_details": {
+    "target_invoked": true/false,
+    "pre_conditions_tested": true/false,
+    "post_conditions_tested": true/false,
+    "test_fixture_used": true/false,
+    "edges_covered": true/false,
+    "invariants_verified": true/false,
+    "ux_states_tested": true/false,
+    "semantic_anchors_present": true/false
+  },
+  "coverage_summary": {
+    "total_edges": number,
+    "edges_tested": number,
+    "total_invariants": number,
+    "invariants_tested": number,
+    "total_ux_states": number,
+    "ux_states_tested": number
+  },
+  "tier_compliance": {
+    "source_tier": "CRITICAL" | "STANDARD" | "TRIVIAL",
+    "meets_tier_requirements": true/false
+  },
+  "feedback": "Strict, actionable feedback for the test generator agent. Explain exactly which anti-pattern was detected and how to fix it."
+}

.kilocode/workflows/speckit.fix.md

@@ -20,7 +20,7 @@ Analyze test failure reports, identify root causes, and fix implementation issue
 
 1. **USE CODER MODE**: Always switch to `coder` mode for code fixes
 2. **SEMANTIC PROTOCOL**: Never remove semantic annotations ([DEF], @TAGS). Only update code logic.
-3. **TEST DATA**: If tests use @TEST_DATA fixtures, preserve them when fixing
+3. **TEST DATA**: If tests use @TEST_ fixtures, preserve them when fixing
 4. **NO DELETION**: Never delete existing tests or semantic annotations
 5. **REPORT FIRST**: Always write a fix report before making changes
 

.kilocode/workflows/speckit.implement.md

@@ -117,7 +117,11 @@ You **MUST** consider the user input before proceeding (if not empty).
    - **Validation checkpoints**: Verify each phase completion before proceeding
 
 7. Implementation execution rules:
-   - **Strict Adherence**: Apply `.ai/standards/semantics.md` rules - every file must start with [DEF] header, include @TIER, and define contracts.
+   - **Strict Adherence**: Apply `.ai/standards/semantics.md` rules:
+     - Every file MUST start with a `[DEF:id:Type]` header and end with a closing `[/DEF:id:Type]` anchor.
+     - Include `@TIER` and define contracts (`@PRE`, `@POST`).
+     - For Svelte components, use `@UX_STATE`, `@UX_FEEDBACK`, `@UX_RECOVERY`, and explicitly declare reactivity with `@UX_REATIVITY: State: $state, Derived: $derived`.
+     - **Molecular Topology Logging**: Use prefixes `[EXPLORE]`, `[REASON]`, `[REFLECT]` in logs to trace logic.
    - **CRITICAL Contracts**: If a task description contains a contract summary (e.g., `CRITICAL: PRE: ..., POST: ...`), these constraints are **MANDATORY** and must be strictly implemented in the code using guards/assertions (if applicable per protocol).
    - **Setup first**: Initialize project structure, dependencies, configuration
    - **Tests before code**: If you need to write tests for contracts, entities, and integration scenarios

.kilocode/workflows/speckit.plan.md

@@ -73,13 +73,13 @@ You **MUST** consider the user input before proceeding (if not empty).
    - Entity name, fields, relationships, validation rules.
 
 2. **Design & Verify Contracts (Semantic Protocol)**:
-   - **Drafting**: Define [DEF] Headers and Contracts for all new modules based on `.ai/standards/semantics.md`.
+   - **Drafting**: Define `[DEF:id:Type]` Headers, Contracts, and closing `[/DEF:id:Type]` for all new modules based on `.ai/standards/semantics.md`.
    - **TIER Classification**: Explicitly assign `@TIER: [CRITICAL|STANDARD|TRIVIAL]` to each module.
-   - **CRITICAL Requirements**: For all CRITICAL modules, define full `@PRE`, `@POST`, and (if UI) `@UX_STATE` contracts.
+   - **CRITICAL Requirements**: For all CRITICAL modules, define full `@PRE`, `@POST`, and (if UI) `@UX_STATE` contracts. **MUST** also define testing contracts: `@TEST_CONTRACT`, `@TEST_FIXTURE`, `@TEST_EDGE`, and `@TEST_INVARIANT`.
    - **Self-Review**:
-     - *Completeness*: Do `@PRE`/`@POST` cover edge cases identified in Research?
+     - *Completeness*: Do `@PRE`/`@POST` cover edge cases identified in Research? Are test contracts present for CRITICAL?
      - *Connectivity*: Do `@RELATION` tags form a coherent graph?
-     - *Compliance*: Does syntax match `[DEF:id:Type]` exactly?
+     - *Compliance*: Does syntax match `[DEF:id:Type]` exactly and is it closed with `[/DEF:id:Type]`?
    - **Output**: Write verified contracts to `contracts/modules.md`.
 
 3. **Simulate Contract Usage**:

.kilocode/workflows/speckit.tasks.md

@@ -121,8 +121,8 @@ Every task MUST strictly follow this format:
 
 2. **From Contracts (CRITICAL TIER)**:
    - Identify components marked as `@TIER: CRITICAL` in `contracts/modules.md`.
-   - For these components, **MUST** append the summary of `@PRE`, `@POST`, and `@UX_STATE` contracts directly to the task description.
-   - Example: `- [ ] T005 [P] [US1] Implement Auth (CRITICAL: PRE: token exists, POST: returns User) in src/auth.py`
+   - For these components, **MUST** append the summary of `@PRE`, `@POST`, `@UX_STATE`, and test contracts (`@TEST_FIXTURE`, `@TEST_EDGE`) directly to the task description.
+   - Example: `- [ ] T005 [P] [US1] Implement Auth (CRITICAL: PRE: token exists, POST: returns User, TESTS: 2 edges) in src/auth.py`
    - Map each contract/endpoint → to the user story it serves
    - If tests requested: Each contract → contract test task [P] before implementation in that story's phase
 

.kilocode/workflows/speckit.test.md

@@ -20,7 +20,7 @@ Execute full testing cycle: analyze code for testable modules, write tests with
 
 1. **NEVER delete existing tests** - Only update if they fail due to bugs in the test or implementation
 2. **NEVER duplicate tests** - Check existing tests first before creating new ones
-3. **Use TEST_DATA fixtures** - For CRITICAL tier modules, read @TEST_DATA from .ai/standards/semantics.md
+3. **Use TEST_FIXTURE fixtures** - For CRITICAL tier modules, read @TEST_FIXTURE from .ai/standards/semantics.md
 4. **Co-location required** - Write tests in `__tests__` directories relative to the code being tested
 
 ## Execution Steps
@@ -42,7 +42,7 @@ Determine:
 
 **From .ai/standards/semantics.md:**
 - Read @TIER annotations for modules
-- For CRITICAL modules: Read @TEST_DATA fixtures
+- For CRITICAL modules: Read @TEST_ fixtures
 
 **From existing tests:**
 - Scan `__tests__` directories for existing tests
@@ -52,8 +52,8 @@ Determine:
 
 Create coverage matrix:
 
-| Module | File | Has Tests | TIER | TEST_DATA Available |
-|--------|------|-----------|------|-------------------|
+| Module | File | Has Tests | TIER | TEST_FIXTURE Available |
+|--------|------|-----------|------|----------------------|
 | ... | ... | ... | ... | ... |
 
 ### 4. Write Tests (TDD Approach)
@@ -61,7 +61,7 @@ Create coverage matrix:
 For each module requiring tests:
 
 1. **Check existing tests**: Scan `__tests__/` for duplicates
-2. **Read TEST_DATA**: If CRITICAL tier, read @TEST_DATA from .ai/standards/semantics.md
+2. **Read TEST_FIXTURE**: If CRITICAL tier, read @TEST_FIXTURE from semantics header
 3. **Write test**: Follow co-location strategy
    - Python: `src/module/__tests__/test_module.py`
    - Svelte: `src/lib/components/__tests__/test_component.test.js`
@@ -102,6 +102,7 @@ describe('Component UX States', () => {
   // @UX_RECOVERY: Retry on error
   it('should allow retry on error', async () => { ... });
 });
+// [/DEF:__tests__/test_Component:Module]
 ```
 
 ### 5. Test Documentation
@@ -170,7 +171,7 @@ Generate test execution report:
 
 - [ ] Fix failed tests
 - [ ] Add more coverage for [module]
-- [ ] Review TEST_DATA fixtures
+- [ ] Review TEST_FIXTURE fixtures
 ```
 
 ## Context for Testing

README.md

@@ -1,143 +1,276 @@
 # ss-tools
 
-Инструменты автоматизации для Apache Superset: миграция, маппинг, хранение артефактов, Git-интеграция, отчеты по задачам и LLM-assistant.
+**Инструменты автоматизации для Apache Superset: миграция, версионирование, аналитика и управление данными**
 
-## Возможности
-- Миграция дашбордов и датасетов между окружениями.
-- Ручной и полуавтоматический маппинг ресурсов.
-- Логи фоновых задач и отчеты о выполнении.
-- Локальное хранилище файлов и бэкапов.
-- Git-операции по Superset-ассетам через UI.
-- Модуль LLM-анализа и assistant API.
-- Многопользовательская авторизация (RBAC).
+## 📋 О проекте
 
-## Стек
-- Backend: Python, FastAPI, SQLAlchemy, APScheduler.
-- Frontend: SvelteKit, Vite, Tailwind CSS.
-- База данных: PostgreSQL (основная конфигурация), поддержка миграции с legacy SQLite.
+ss-tools — это комплексная платформа для автоматизации работы с Apache Superset, предоставляющая инструменты для миграции дашбордов, управления версиями через Git, LLM-анализа данных и многопользовательского контроля доступа. Система построена на модульной архитектуре с плагинной системой расширений.
 
-## Структура репозитория
-- `backend/` — API, плагины, сервисы, скрипты миграции и тесты.
-- `frontend/` — SPA-интерфейс (SvelteKit).
-- `docs/` — документация по архитектуре и плагинам.
-- `specs/` — спецификации и планы реализации.
-- `docker/` и `docker-compose.yml` — контейнеризация.
+### 🎯 Ключевые возможности
 
-## Быстрый старт (локально)
+#### 🔄 Миграция данных
+- **Миграция дашбордов и датасетов** между окружениями (dev/staging/prod)
+- **Dry-run режим** с детальным анализом рисков и предпросмотром изменений
+- **Автоматическое маппинг** баз данных и ресурсов между окружениями
+- **Поддержка legacy-данных** с миграцией из SQLite в PostgreSQL
+
+#### 🌿 Git-интеграция
+- **Версионирование** дашбордов через Git-репозитории
+- **Управление ветками** и коммитами с помощью LLM
+- **Деплой** дашбордов из Git в целевые окружения
+- **История изменений** с детальным diff
+
+#### 🤖 LLM-аналитика
+- **Автоматическая валидация** дашбордов с помощью ИИ
+- **Генерация документации** для датасетов
+- **Assistant API** для natural language команд
+- **Интеллектуальное коммитинг** с подсказками сообщений
+
+#### 📊 Управление и мониторинг
+- **Многопользовательская авторизация** (RBAC)
+- **Фоновые задачи** с реальным логированием через WebSocket
+- **Унифицированные отчеты** по выполненным задачам
+- **Хранение артефактов** с политиками retention
+- **Аудит логирование** всех действий
+
+#### 🔌 Плагины
+- **MigrationPlugin** — миграция дашбордов
+- **BackupPlugin** — резервное копирование
+- **GitPlugin** — управление версиями
+- **LLMAnalysisPlugin** — аналитика и документация
+- **MapperPlugin** — маппинг колонок
+- **DebugPlugin** — диагностика системы
+- **SearchPlugin** — поиск по датасетам
+
+## 🏗️ Архитектура
+
+### Технологический стек
+
+**Backend:**
+- Python 3.9+ (FastAPI, SQLAlchemy, APScheduler)
+- PostgreSQL (основная БД)
+- GitPython для Git-операций
+- OpenAI API для LLM-функций
+- Playwright для скриншотов
+
+**Frontend:**
+- SvelteKit (Svelte 5.x)
+- Vite
+- Tailwind CSS
+- WebSocket для реального логирования
+
+**DevOps:**
+- Docker & Docker Compose
+- PostgreSQL 16
+
+### Модульная структура
+
+```
+ss-tools/
+├── backend/                    # Backend API
+│   ├── src/
+│   │   ├── api/               # API маршруты
+│   │   ├── core/              # Ядро системы
+│   │   │   ├── task_manager/  # Управление задачами
+│   │   │   ├── auth/          # Авторизация
+│   │   │   ├── migration/     # Миграция данных
+│   │   │   └── plugins/       # Плагины
+│   │   ├── models/            # Модели данных
+│   │   ├── services/          # Бизнес-логика
+│   │   └── schemas/           # Pydantic схемы
+│   └── tests/                 # Тесты
+├── frontend/                   # SvelteKit приложение
+│   ├── src/
+│   │   ├── routes/            # Страницы
+│   │   ├── lib/
+│   │   │   ├── components/    # UI компоненты
+│   │   │   ├── stores/        # Svelte stores
+│   │   │   └── api/           # API клиент
+│   │   └── i18n/              # Мультиязычность
+│   └── tests/
+├── docker/                     # Docker конфигурация
+├── docs/                       # Документация
+└── specs/                      # Спецификации
+```
+
+## 🚀 Быстрый старт
 
 ### Требования
+
+**Локальная разработка:**
 - Python 3.9+
 - Node.js 18+
 - npm
+- 2 GB RAM (минимум)
+- 5 GB свободного места
+
+**Docker (рекомендуется):**
+- Docker Engine 24+
+- Docker Compose v2
+- 4 GB RAM (для стабильной работы)
+
+### Установка и запуск
+
+#### Вариант 1: Docker (рекомендуется)
 
-### Запуск backend + frontend одним скриптом
 ```bash
-./run.sh
-```
+# Клонирование репозитория
+git clone <repository-url>
+cd ss-tools
 
-Что делает `run.sh`:
-- проверяет версии Python/npm;
-- создает `backend/.venv` (если нет);
-- устанавливает `backend/requirements.txt` и `frontend` зависимости;
-- запускает backend и frontend параллельно.
-
-Опции:
-- `./run.sh --skip-install` — пропустить установку зависимостей.
-- `./run.sh --help` — показать справку.
-
-Переменные окружения для локального запуска:
-- `BACKEND_PORT` (по умолчанию `8000`)
-- `FRONTEND_PORT` (по умолчанию `5173`)
-- `POSTGRES_URL`
-- `DATABASE_URL`
-- `TASKS_DATABASE_URL`
-- `AUTH_DATABASE_URL`
-
-## Docker
-
-### Запуск
-```bash
+# Запуск всех сервисов
 docker compose up --build
+
+# После запуска:
+# Frontend: http://localhost:8000
+# Backend API: http://localhost:8001
+# PostgreSQL: localhost:5432
 ```
 
-После старта сервисы доступны по адресам:
-- Frontend: `http://localhost:8000`
-- Backend API: `http://localhost:8001`
-- PostgreSQL: `localhost:5432` (`postgres/postgres`, БД `ss_tools`)
+#### Вариант 2: Локально
 
-### Остановка
-```bash
-docker compose down
-```
-
-### Очистка БД-тома
-```bash
-docker compose down -v
-```
-
-### Альтернативный образ PostgreSQL
-Если есть проблемы с pull `postgres:16-alpine`:
-```bash
-POSTGRES_IMAGE=mirror.gcr.io/library/postgres:16-alpine docker compose up -d db
-```
-или
-```bash
-POSTGRES_IMAGE=bitnami/postgresql:latest docker compose up -d db
-```
-
-Если порт `5432` занят:
-```bash
-POSTGRES_HOST_PORT=5433 docker compose up -d db
-```
-
-## Разработка
-
-### Ручной запуск сервисов
 ```bash
+# Backend
 cd backend
 python3 -m venv .venv
 source .venv/bin/activate
 pip install -r requirements.txt
 python3 -m uvicorn src.app:app --reload --port 8000
-```
 
-В другом терминале:
-```bash
+# Frontend (в новом терминале)
 cd frontend
 npm install
 npm run dev -- --port 5173
 ```
 
-### Тесты
-Backend:
-```bash
-cd backend
-source .venv/bin/activate
-pytest
-```
+### Первичная настройка
 
-Frontend:
-```bash
-cd frontend
-npm run test
-```
-
-## Инициализация auth (опционально)
 ```bash
+# Инициализация БД
 cd backend
 source .venv/bin/activate
 python src/scripts/init_auth_db.py
+
+# Создание администратора
 python src/scripts/create_admin.py --username admin --password admin
 ```
 
-## Миграция legacy-данных (опционально)
+## 🏢 Enterprise Clean Deployment (internal-only)
+
+Для разворота в корпоративной сети используйте профиль enterprise clean:
+
+- очищенный дистрибутив без test/demo/load-test данных;
+- запрет внешних интернет-источников;
+- загрузка ресурсов только с внутренних серверов компании;
+- обязательная блокирующая проверка clean/compliance перед выпуском.
+
+Быстрый запуск TUI-проверки:
+
 ```bash
-cd backend
-source .venv/bin/activate
-PYTHONPATH=. python src/scripts/migrate_sqlite_to_postgres.py --sqlite-path tasks.db
+cd /home/busya/dev/ss-tools
+./backend/.venv/bin/python3 -m backend.src.scripts.clean_release_tui
 ```
 
-## Дополнительная документация
-- `docs/plugin_dev.md`
-- `docs/settings.md`
-- `semantic_protocol.md`
+Типовые внутренние источники:
+- `repo.intra.company.local`
+- `artifacts.intra.company.local`
+- `pypi.intra.company.local`
+
+Если найден внешний endpoint, выпуск получает статус `BLOCKED` до исправления.
+
+## 📖 Документация
+
+- [Установка и настройка](docs/installation.md)
+- [Архитектура системы](docs/architecture.md)
+- [Разработка плагинов](docs/plugin_dev.md)
+- [API документация](http://localhost:8001/docs)
+- [Настройка окружений](docs/settings.md)
+
+## 🧪 Тестирование
+
+```bash
+# Backend тесты
+cd backend
+source .venv/bin/activate
+pytest
+
+# Frontend тесты
+cd frontend
+npm run test
+
+# Запуск конкретного теста
+pytest tests/test_auth.py::test_create_user
+```
+
+
+
+## 🔐 Авторизация
+
+Система поддерживает два метода аутентификации:
+
+1. **Локальная аутентификация** (username/password)
+2. **ADFS SSO** (Active Directory Federation Services)
+
+### Управление пользователями и ролями
+
+```bash
+# Получение списка пользователей
+GET /api/admin/users
+
+# Создание пользователя
+POST /api/admin/users
+{
+  "username": "newuser",
+  "email": "user@example.com",
+  "password": "password123",
+  "roles": ["analyst"]
+}
+
+# Создание роли
+POST /api/admin/roles
+{
+  "name": "analyst",
+  "permissions": ["dashboards:read", "dashboards:write"]
+}
+```
+
+## 📊 Мониторинг
+
+### Отчеты о задачах
+
+```bash
+# Список всех отчетов
+GET /api/reports?page=1&page_size=20
+
+# Детали отчета
+GET /api/reports/{report_id}
+
+# Фильтры
+GET /api/reports?status=failed&task_type=validation&date_from=2024-01-01
+```
+
+### Активность
+
+- **Dashboard Hub** — управление дашбордами с Git-статусом
+- **Dataset Hub** — управление датасетами с прогрессом маппинга
+- **Task Drawer** — мониторинг выполнения фоновых задач
+- **Unified Reports** — унифицированные отчеты по всем типам задач
+
+## 🔄 Обновление системы
+
+```bash
+# Обновление Docker контейнеров
+docker compose pull
+docker compose up -d
+
+# Обновление зависимостей Python
+cd backend
+source .venv/bin/activate
+pip install -r requirements.txt --upgrade
+
+# Обновление зависимостей Node.js
+cd frontend
+npm install
+```
+
+

backend/src/api/routes/__init__.py

@@ -6,7 +6,7 @@
 # @RELATION: DEPENDS_ON -> importlib
 # @INVARIANT: Only names listed in __all__ are importable via __getattr__.
 
-__all__ = ['plugins', 'tasks', 'settings', 'connections', 'environments', 'mappings', 'migration', 'git', 'storage', 'admin', 'reports', 'assistant']
+__all__ = ['plugins', 'tasks', 'settings', 'connections', 'environments', 'mappings', 'migration', 'git', 'storage', 'admin', 'reports', 'assistant', 'clean_release']
 
 
 # [DEF:__getattr__:Function]

backend/src/api/routes/__tests__/test_assistant_api.py

@@ -76,11 +76,15 @@ class _FakeTaskManager:
 class _FakeConfigManager:
     def get_environments(self):
         return [
-            SimpleNamespace(id="dev", name="Development"),
-            SimpleNamespace(id="prod", name="Production"),
+            SimpleNamespace(id="dev", name="Development", url="http://dev", credentials_id="dev", username="fakeuser", password="fakepassword"),
+            SimpleNamespace(id="prod", name="Production", url="http://prod", credentials_id="prod", username="fakeuser", password="fakepassword"),
         ]
 
-
+    def get_config(self):
+        return SimpleNamespace(
+            settings=SimpleNamespace(migration_sync_cron="0 0 * * *"),
+            environments=self.get_environments()
+        )
 # [/DEF:_FakeConfigManager:Class]
 # [DEF:_admin_user:Function]
 # @TIER: TRIVIAL
@@ -645,5 +649,49 @@ def test_confirm_nonexistent_id_returns_404():
     assert exc.value.status_code == 404
 
 
-# [/DEF:test_guarded_operation_confirm_roundtrip:Function]
+# [DEF:test_migration_with_dry_run_includes_summary:Function]
+# @PURPOSE: Migration command with dry run flag must return the dry run summary in confirmation text.
+# @PRE: user specifies a migration with --dry-run flag.
+# @POST: Response state is needs_confirmation and text contains dry-run summary counts.
+def test_migration_with_dry_run_includes_summary(monkeypatch):
+    import src.core.migration.dry_run_orchestrator as dry_run_module
+    from unittest.mock import MagicMock
+    _clear_assistant_state()
+    task_manager = _FakeTaskManager()
+    db = _FakeDb()
+
+    class _FakeDryRunService:
+        def run(self, selection, source_client, target_client, db_session):
+            return {
+                "summary": {
+                    "dashboards": {"create": 1, "update": 0, "delete": 0},
+                    "charts": {"create": 3, "update": 2, "delete": 1},
+                    "datasets": {"create": 0, "update": 1, "delete": 0}
+                }
+            }
+            
+    monkeypatch.setattr(dry_run_module, "MigrationDryRunService", _FakeDryRunService)
+    
+    import src.core.superset_client as superset_client_module
+    monkeypatch.setattr(superset_client_module, "SupersetClient", lambda env: MagicMock())
+
+    start = _run_async(
+        assistant_module.send_message(
+            request=assistant_module.AssistantMessageRequest(
+                message="миграция с dev на prod для дашборда 10 --dry-run"
+            ),
+            current_user=_admin_user(),
+            task_manager=task_manager,
+            config_manager=_FakeConfigManager(),
+            db=db,
+        )
+    )
+
+    assert start.state == "needs_confirmation"
+    assert "отчет dry-run: ВКЛ" in start.text
+    assert "Отчет dry-run:" in start.text
+    assert "создано новых объектов: 4" in start.text
+    assert "обновлено: 3" in start.text
+    assert "удалено: 1" in start.text
+# [/DEF:test_migration_with_dry_run_includes_summary:Function]
 # [/DEF:backend.src.api.routes.__tests__.test_assistant_api:Module]

backend/src/api/routes/__tests__/test_dashboards.py

@@ -10,6 +10,41 @@ from datetime import datetime, timezone
 from fastapi.testclient import TestClient
 from src.app import app
 from src.api.routes.dashboards import DashboardsResponse
+from src.dependencies import get_current_user, has_permission, get_config_manager, get_task_manager, get_resource_service, get_mapping_service
+
+# Global mock user for get_current_user dependency overrides
+mock_user = MagicMock()
+mock_user.username = "testuser"
+mock_user.roles = []
+admin_role = MagicMock()
+admin_role.name = "Admin"
+mock_user.roles.append(admin_role)
+
+@pytest.fixture(autouse=True)
+def mock_deps():
+    config_manager = MagicMock()
+    task_manager = MagicMock()
+    resource_service = MagicMock()
+    mapping_service = MagicMock()
+    
+    app.dependency_overrides[get_config_manager] = lambda: config_manager
+    app.dependency_overrides[get_task_manager] = lambda: task_manager
+    app.dependency_overrides[get_resource_service] = lambda: resource_service
+    app.dependency_overrides[get_mapping_service] = lambda: mapping_service
+    app.dependency_overrides[get_current_user] = lambda: mock_user
+    
+    app.dependency_overrides[has_permission("plugin:migration", "READ")] = lambda: mock_user
+    app.dependency_overrides[has_permission("plugin:migration", "EXECUTE")] = lambda: mock_user
+    app.dependency_overrides[has_permission("plugin:backup", "EXECUTE")] = lambda: mock_user
+    app.dependency_overrides[has_permission("tasks", "READ")] = lambda: mock_user
+    
+    yield {
+        "config": config_manager,
+        "task": task_manager,
+        "resource": resource_service,
+        "mapping": mapping_service
+    }
+    app.dependency_overrides.clear()
 
 client = TestClient(app)
 
@@ -18,45 +53,35 @@ client = TestClient(app)
 # @TEST: GET /api/dashboards returns 200 and valid schema
 # @PRE: env_id exists
 # @POST: Response matches DashboardsResponse schema
-def test_get_dashboards_success():
-    with patch("src.api.routes.dashboards.get_config_manager") as mock_config, \
-         patch("src.api.routes.dashboards.get_resource_service") as mock_service, \
-         patch("src.api.routes.dashboards.get_task_manager") as mock_task_mgr, \
-         patch("src.api.routes.dashboards.has_permission") as mock_perm:
-        
-        # Mock environment
-        mock_env = MagicMock()
-        mock_env.id = "prod"
-        mock_config.return_value.get_environments.return_value = [mock_env]
-        
-        # Mock task manager
-        mock_task_mgr.return_value.get_all_tasks.return_value = []
-        
-        # Mock resource service response
-        async def mock_get_dashboards(env, tasks):
-            return [
-                {
-                    "id": 1,
-                    "title": "Sales Report",
-                    "slug": "sales",
-                    "git_status": {"branch": "main", "sync_status": "OK"},
-                    "last_task": {"task_id": "task-1", "status": "SUCCESS"}
-                }
-            ]
-        mock_service.return_value.get_dashboards_with_status = AsyncMock(
-            side_effect=mock_get_dashboards
-        )
-        
-        # Mock permission
-        mock_perm.return_value = lambda: True
+def test_get_dashboards_success(mock_deps):
+    """Uses @TEST_FIXTURE: dashboard_list_happy data."""
+    mock_env = MagicMock()
+    mock_env.id = "prod"
+    mock_deps["config"].get_environments.return_value = [mock_env]
+    mock_deps["task"].get_all_tasks.return_value = []
 
-        response = client.get("/api/dashboards?env_id=prod")
-        
-        assert response.status_code == 200
-        data = response.json()
-        assert "dashboards" in data
-        assert "total" in data
-        assert "page" in data
+    # @TEST_FIXTURE: dashboard_list_happy -> {"id": 1, "title": "Main Revenue"}
+    mock_deps["resource"].get_dashboards_with_status = AsyncMock(return_value=[
+        {
+            "id": 1,
+            "title": "Main Revenue",
+            "slug": "main-revenue",
+            "git_status": {"branch": "main", "sync_status": "OK"},
+            "last_task": {"task_id": "task-1", "status": "SUCCESS"}
+        }
+    ])
+
+    response = client.get("/api/dashboards?env_id=prod")
+
+    assert response.status_code == 200
+    data = response.json()
+    # exhaustive @POST assertions
+    assert "dashboards" in data
+    assert len(data["dashboards"]) == 1
+    assert data["dashboards"][0]["title"] == "Main Revenue"
+    assert data["total"] == 1
+    assert "page" in data
+    DashboardsResponse(**data)
 
 
 # [/DEF:test_get_dashboards_success:Function]
@@ -66,55 +91,81 @@ def test_get_dashboards_success():
 # @TEST: GET /api/dashboards filters by search term
 # @PRE: search parameter provided
 # @POST: Only matching dashboards returned
-def test_get_dashboards_with_search():
-    with patch("src.api.routes.dashboards.get_config_manager") as mock_config, \
-         patch("src.api.routes.dashboards.get_resource_service") as mock_service, \
-         patch("src.api.routes.dashboards.get_task_manager") as mock_task_mgr, \
-         patch("src.api.routes.dashboards.has_permission") as mock_perm:
-        
-        # Mock environment
-        mock_env = MagicMock()
-        mock_env.id = "prod"
-        mock_config.return_value.get_environments.return_value = [mock_env]
-        
-        mock_task_mgr.return_value.get_all_tasks.return_value = []
-        
-        async def mock_get_dashboards(env, tasks):
-            return [
-                {"id": 1, "title": "Sales Report", "slug": "sales"},
-                {"id": 2, "title": "Marketing Dashboard", "slug": "marketing"}
-            ]
-        mock_service.return_value.get_dashboards_with_status = AsyncMock(
-            side_effect=mock_get_dashboards
-        )
-        
-        mock_perm.return_value = lambda: True
+def test_get_dashboards_with_search(mock_deps):
+    mock_env = MagicMock()
+    mock_env.id = "prod"
+    mock_deps["config"].get_environments.return_value = [mock_env]
+    mock_deps["task"].get_all_tasks.return_value = []
 
-        response = client.get("/api/dashboards?env_id=prod&search=sales")
-        
-        assert response.status_code == 200
-        data = response.json()
-        # Filtered by search term
+    async def mock_get_dashboards(env, tasks):
+        return [
+            {"id": 1, "title": "Sales Report", "slug": "sales"},
+            {"id": 2, "title": "Marketing Dashboard", "slug": "marketing"}
+        ]
+    mock_deps["resource"].get_dashboards_with_status = AsyncMock(
+        side_effect=mock_get_dashboards
+    )
+
+    response = client.get("/api/dashboards?env_id=prod&search=sales")
+
+    assert response.status_code == 200
+    data = response.json()
+    # @POST: Filtered result count must match search
+    assert len(data["dashboards"]) == 1
+    assert data["dashboards"][0]["title"] == "Sales Report"
 
 
 # [/DEF:test_get_dashboards_with_search:Function]
 
 
+# [DEF:test_get_dashboards_empty:Function]
+# @TEST_EDGE: empty_dashboards -> {env_id: 'empty_env', expected_total: 0}
+def test_get_dashboards_empty(mock_deps):
+    """@TEST_EDGE: empty_dashboards -> {env_id: 'empty_env', expected_total: 0}"""
+    mock_env = MagicMock()
+    mock_env.id = "empty_env"
+    mock_deps["config"].get_environments.return_value = [mock_env]
+    mock_deps["task"].get_all_tasks.return_value = []
+    mock_deps["resource"].get_dashboards_with_status = AsyncMock(return_value=[])
+
+    response = client.get("/api/dashboards?env_id=empty_env")
+    assert response.status_code == 200
+    data = response.json()
+    assert data["total"] == 0
+    assert len(data["dashboards"]) == 0
+    assert data["total_pages"] == 1
+    DashboardsResponse(**data)
+# [/DEF:test_get_dashboards_empty:Function]
+
+
+# [DEF:test_get_dashboards_superset_failure:Function]
+# @TEST_EDGE: external_superset_failure -> {env_id: 'bad_conn', status: 503}
+def test_get_dashboards_superset_failure(mock_deps):
+    """@TEST_EDGE: external_superset_failure -> {env_id: 'bad_conn', status: 503}"""
+    mock_env = MagicMock()
+    mock_env.id = "bad_conn"
+    mock_deps["config"].get_environments.return_value = [mock_env]
+    mock_deps["task"].get_all_tasks.return_value = []
+    mock_deps["resource"].get_dashboards_with_status = AsyncMock(
+        side_effect=Exception("Connection refused")
+    )
+
+    response = client.get("/api/dashboards?env_id=bad_conn")
+    assert response.status_code == 503
+    assert "Failed to fetch dashboards" in response.json()["detail"]
+# [/DEF:test_get_dashboards_superset_failure:Function]
+
+
 # [DEF:test_get_dashboards_env_not_found:Function]
 # @TEST: GET /api/dashboards returns 404 if env_id missing
 # @PRE: env_id does not exist
 # @POST: Returns 404 error
-def test_get_dashboards_env_not_found():
-    with patch("src.api.routes.dashboards.get_config_manager") as mock_config, \
-         patch("src.api.routes.dashboards.has_permission") as mock_perm:
-        
-        mock_config.return_value.get_environments.return_value = []
-        mock_perm.return_value = lambda: True
-
-        response = client.get("/api/dashboards?env_id=nonexistent")
-        
-        assert response.status_code == 404
-        assert "Environment not found" in response.json()["detail"]
+def test_get_dashboards_env_not_found(mock_deps):
+    mock_deps["config"].get_environments.return_value = []
+    response = client.get("/api/dashboards?env_id=nonexistent")
+    
+    assert response.status_code == 404
+    assert "Environment not found" in response.json()["detail"]
 
 
 # [/DEF:test_get_dashboards_env_not_found:Function]
@@ -124,40 +175,29 @@ def test_get_dashboards_env_not_found():
 # @TEST: GET /api/dashboards returns 400 for invalid page/page_size
 # @PRE: page < 1 or page_size > 100
 # @POST: Returns 400 error
-def test_get_dashboards_invalid_pagination():
-    with patch("src.api.routes.dashboards.get_config_manager") as mock_config, \
-         patch("src.api.routes.dashboards.has_permission") as mock_perm:
+def test_get_dashboards_invalid_pagination(mock_deps):
+    mock_env = MagicMock()
+    mock_env.id = "prod"
+    mock_deps["config"].get_environments.return_value = [mock_env]
+    # Invalid page
+    response = client.get("/api/dashboards?env_id=prod&page=0")
+    assert response.status_code == 400
+    assert "Page must be >= 1" in response.json()["detail"]
         
-        mock_env = MagicMock()
-        mock_env.id = "prod"
-        mock_config.return_value.get_environments.return_value = [mock_env]
-        mock_perm.return_value = lambda: True
-
-        # Invalid page
-        response = client.get("/api/dashboards?env_id=prod&page=0")
-        assert response.status_code == 400
-        assert "Page must be >= 1" in response.json()["detail"]
-        
-        # Invalid page_size
-        response = client.get("/api/dashboards?env_id=prod&page_size=101")
-        assert response.status_code == 400
-        assert "Page size must be between 1 and 100" in response.json()["detail"]
-
-
+    # Invalid page_size
+    response = client.get("/api/dashboards?env_id=prod&page_size=101")
+    assert response.status_code == 400
+    assert "Page size must be between 1 and 100" in response.json()["detail"]
 # [/DEF:test_get_dashboards_invalid_pagination:Function]
 
 
 # [DEF:test_get_dashboard_detail_success:Function]
 # @TEST: GET /api/dashboards/{id} returns dashboard detail with charts and datasets
-def test_get_dashboard_detail_success():
-    with patch("src.api.routes.dashboards.get_config_manager") as mock_config, \
-         patch("src.api.routes.dashboards.has_permission") as mock_perm, \
-         patch("src.api.routes.dashboards.SupersetClient") as mock_client_cls:
-
+def test_get_dashboard_detail_success(mock_deps):
+    with patch("src.api.routes.dashboards.SupersetClient") as mock_client_cls:
         mock_env = MagicMock()
         mock_env.id = "prod"
-        mock_config.return_value.get_environments.return_value = [mock_env]
-        mock_perm.return_value = lambda: True
+        mock_deps["config"].get_environments.return_value = [mock_env]
 
         mock_client = MagicMock()
         mock_client.get_dashboard_detail.return_value = {
@@ -205,56 +245,46 @@ def test_get_dashboard_detail_success():
 
 # [DEF:test_get_dashboard_detail_env_not_found:Function]
 # @TEST: GET /api/dashboards/{id} returns 404 for missing environment
-def test_get_dashboard_detail_env_not_found():
-    with patch("src.api.routes.dashboards.get_config_manager") as mock_config, \
-         patch("src.api.routes.dashboards.has_permission") as mock_perm:
-        mock_config.return_value.get_environments.return_value = []
-        mock_perm.return_value = lambda: True
+def test_get_dashboard_detail_env_not_found(mock_deps):
+    mock_deps["config"].get_environments.return_value = []
+    
+    response = client.get("/api/dashboards/42?env_id=missing")
 
-        response = client.get("/api/dashboards/42?env_id=missing")
-
-        assert response.status_code == 404
-        assert "Environment not found" in response.json()["detail"]
+    assert response.status_code == 404
+    assert "Environment not found" in response.json()["detail"]
 # [/DEF:test_get_dashboard_detail_env_not_found:Function]
 
 
 # [DEF:test_migrate_dashboards_success:Function]
 # @TEST: POST /api/dashboards/migrate creates migration task
 # @PRE: Valid source_env_id, target_env_id, dashboard_ids
-# @POST: Returns task_id
-def test_migrate_dashboards_success():
-    with patch("src.api.routes.dashboards.get_config_manager") as mock_config, \
-         patch("src.api.routes.dashboards.get_task_manager") as mock_task_mgr, \
-         patch("src.api.routes.dashboards.has_permission") as mock_perm:
-        
-        # Mock environments
-        mock_source = MagicMock()
-        mock_source.id = "source"
-        mock_target = MagicMock()
-        mock_target.id = "target"
-        mock_config.return_value.get_environments.return_value = [mock_source, mock_target]
-        
-        # Mock task manager
-        mock_task = MagicMock()
-        mock_task.id = "task-migrate-123"
-        mock_task_mgr.return_value.create_task = AsyncMock(return_value=mock_task)
-        
-        # Mock permission
-        mock_perm.return_value = lambda: True
+# @POST: Returns task_id and create_task was called
+def test_migrate_dashboards_success(mock_deps):
+    mock_source = MagicMock()
+    mock_source.id = "source"
+    mock_target = MagicMock()
+    mock_target.id = "target"
+    mock_deps["config"].get_environments.return_value = [mock_source, mock_target]
 
-        response = client.post(
-            "/api/dashboards/migrate",
-            json={
-                "source_env_id": "source",
-                "target_env_id": "target",
-                "dashboard_ids": [1, 2, 3],
-                "db_mappings": {"old_db": "new_db"}
-            }
-        )
-        
-        assert response.status_code == 200
-        data = response.json()
-        assert "task_id" in data
+    mock_task = MagicMock()
+    mock_task.id = "task-migrate-123"
+    mock_deps["task"].create_task = AsyncMock(return_value=mock_task)
+
+    response = client.post(
+        "/api/dashboards/migrate",
+        json={
+            "source_env_id": "source",
+            "target_env_id": "target",
+            "dashboard_ids": [1, 2, 3],
+            "db_mappings": {"old_db": "new_db"}
+        }
+    )
+
+    assert response.status_code == 200
+    data = response.json()
+    assert "task_id" in data
+    # @POST/@SIDE_EFFECT: create_task was called
+    mock_deps["task"].create_task.assert_called_once()
 
 
 # [/DEF:test_migrate_dashboards_success:Function]
@@ -264,154 +294,184 @@ def test_migrate_dashboards_success():
 # @TEST: POST /api/dashboards/migrate returns 400 for empty dashboard_ids
 # @PRE: dashboard_ids is empty
 # @POST: Returns 400 error
-def test_migrate_dashboards_no_ids():
-    with patch("src.api.routes.dashboards.has_permission") as mock_perm:
-        mock_perm.return_value = lambda: True
+def test_migrate_dashboards_no_ids(mock_deps):
+    response = client.post(
+        "/api/dashboards/migrate",
+        json={
+            "source_env_id": "source",
+            "target_env_id": "target",
+            "dashboard_ids": []
+        }
+    )
 
-        response = client.post(
-            "/api/dashboards/migrate",
-            json={
-                "source_env_id": "source",
-                "target_env_id": "target",
-                "dashboard_ids": []
-            }
-        )
-        
-        assert response.status_code == 400
-        assert "At least one dashboard ID must be provided" in response.json()["detail"]
+    assert response.status_code == 400
+    assert "At least one dashboard ID must be provided" in response.json()["detail"]
 
 
 # [/DEF:test_migrate_dashboards_no_ids:Function]
 
 
+# [DEF:test_migrate_dashboards_env_not_found:Function]
+# @PRE: source_env_id and target_env_id are valid environment IDs
+def test_migrate_dashboards_env_not_found(mock_deps):
+    """@PRE: source_env_id and target_env_id are valid environment IDs."""
+    mock_deps["config"].get_environments.return_value = []
+    response = client.post(
+        "/api/dashboards/migrate",
+        json={
+            "source_env_id": "ghost",
+            "target_env_id": "t",
+            "dashboard_ids": [1]
+        }
+    )
+    assert response.status_code == 404
+    assert "Source environment not found" in response.json()["detail"]
+# [/DEF:test_migrate_dashboards_env_not_found:Function]
+
+
 # [DEF:test_backup_dashboards_success:Function]
 # @TEST: POST /api/dashboards/backup creates backup task
 # @PRE: Valid env_id, dashboard_ids
-# @POST: Returns task_id
-def test_backup_dashboards_success():
-    with patch("src.api.routes.dashboards.get_config_manager") as mock_config, \
-         patch("src.api.routes.dashboards.get_task_manager") as mock_task_mgr, \
-         patch("src.api.routes.dashboards.has_permission") as mock_perm:
-        
-        # Mock environment
-        mock_env = MagicMock()
-        mock_env.id = "prod"
-        mock_config.return_value.get_environments.return_value = [mock_env]
-        
-        # Mock task manager
-        mock_task = MagicMock()
-        mock_task.id = "task-backup-456"
-        mock_task_mgr.return_value.create_task = AsyncMock(return_value=mock_task)
-        
-        # Mock permission
-        mock_perm.return_value = lambda: True
+# @POST: Returns task_id and create_task was called
+def test_backup_dashboards_success(mock_deps):
+    mock_env = MagicMock()
+    mock_env.id = "prod"
+    mock_deps["config"].get_environments.return_value = [mock_env]
 
-        response = client.post(
-            "/api/dashboards/backup",
-            json={
-                "env_id": "prod",
-                "dashboard_ids": [1, 2, 3],
-                "schedule": "0 0 * * *"
-            }
-        )
-        
-        assert response.status_code == 200
-        data = response.json()
-        assert "task_id" in data
+    mock_task = MagicMock()
+    mock_task.id = "task-backup-456"
+    mock_deps["task"].create_task = AsyncMock(return_value=mock_task)
+
+    response = client.post(
+        "/api/dashboards/backup",
+        json={
+            "env_id": "prod",
+            "dashboard_ids": [1, 2, 3],
+            "schedule": "0 0 * * *"
+        }
+    )
+
+    assert response.status_code == 200
+    data = response.json()
+    assert "task_id" in data
+    # @POST/@SIDE_EFFECT: create_task was called
+    mock_deps["task"].create_task.assert_called_once()
 
 
 # [/DEF:test_backup_dashboards_success:Function]
 
 
+# [DEF:test_backup_dashboards_env_not_found:Function]
+# @PRE: env_id is a valid environment ID
+def test_backup_dashboards_env_not_found(mock_deps):
+    """@PRE: env_id is a valid environment ID."""
+    mock_deps["config"].get_environments.return_value = []
+    response = client.post(
+        "/api/dashboards/backup",
+        json={
+            "env_id": "ghost",
+            "dashboard_ids": [1]
+        }
+    )
+    assert response.status_code == 404
+    assert "Environment not found" in response.json()["detail"]
+# [/DEF:test_backup_dashboards_env_not_found:Function]
+
+
 # [DEF:test_get_database_mappings_success:Function]
 # @TEST: GET /api/dashboards/db-mappings returns mapping suggestions
 # @PRE: Valid source_env_id, target_env_id
 # @POST: Returns list of database mappings
-def test_get_database_mappings_success():
-    with patch("src.api.routes.dashboards.get_mapping_service") as mock_service, \
-         patch("src.api.routes.dashboards.has_permission") as mock_perm:
-        
-        # Mock mapping service
-        mock_service.return_value.get_suggestions = AsyncMock(return_value=[
-            {
-                "source_db": "old_sales",
-                "target_db": "new_sales",
-                "source_db_uuid": "uuid-1",
-                "target_db_uuid": "uuid-2",
-                "confidence": 0.95
-            }
-        ])
-        
-        # Mock permission
-        mock_perm.return_value = lambda: True
+def test_get_database_mappings_success(mock_deps):
+    mock_source = MagicMock()
+    mock_source.id = "prod"
+    mock_target = MagicMock()
+    mock_target.id = "staging"
+    mock_deps["config"].get_environments.return_value = [mock_source, mock_target]
 
-        response = client.get("/api/dashboards/db-mappings?source_env_id=prod&target_env_id=staging")
-        
-        assert response.status_code == 200
-        data = response.json()
-        assert "mappings" in data
+    mock_deps["mapping"].get_suggestions = AsyncMock(return_value=[
+        {
+            "source_db": "old_sales",
+            "target_db": "new_sales",
+            "source_db_uuid": "uuid-1",
+            "target_db_uuid": "uuid-2",
+            "confidence": 0.95
+        }
+    ])
+
+    response = client.get("/api/dashboards/db-mappings?source_env_id=prod&target_env_id=staging")
+
+    assert response.status_code == 200
+    data = response.json()
+    assert "mappings" in data
+    assert len(data["mappings"]) == 1
+    assert data["mappings"][0]["confidence"] == 0.95
 
 
 # [/DEF:test_get_database_mappings_success:Function]
 
 
+# [DEF:test_get_database_mappings_env_not_found:Function]
+# @PRE: source_env_id and target_env_id are valid environment IDs
+def test_get_database_mappings_env_not_found(mock_deps):
+    """@PRE: source_env_id must be a valid environment."""
+    mock_deps["config"].get_environments.return_value = []
+    response = client.get("/api/dashboards/db-mappings?source_env_id=ghost&target_env_id=t")
+    assert response.status_code == 404
+# [/DEF:test_get_database_mappings_env_not_found:Function]
+
+
 # [DEF:test_get_dashboard_tasks_history_filters_success:Function]
 # @TEST: GET /api/dashboards/{id}/tasks returns backup and llm tasks for dashboard
-def test_get_dashboard_tasks_history_filters_success():
-    with patch("src.api.routes.dashboards.get_task_manager") as mock_task_mgr, \
-         patch("src.api.routes.dashboards.has_permission") as mock_perm:
-        now = datetime.now(timezone.utc)
+def test_get_dashboard_tasks_history_filters_success(mock_deps):
+    now = datetime.now(timezone.utc)
 
-        llm_task = MagicMock()
-        llm_task.id = "task-llm-1"
-        llm_task.plugin_id = "llm_dashboard_validation"
-        llm_task.status = "SUCCESS"
-        llm_task.started_at = now
-        llm_task.finished_at = now
-        llm_task.params = {"dashboard_id": "42", "environment_id": "prod"}
-        llm_task.result = {"summary": "LLM validation complete"}
+    llm_task = MagicMock()
+    llm_task.id = "task-llm-1"
+    llm_task.plugin_id = "llm_dashboard_validation"
+    llm_task.status = "SUCCESS"
+    llm_task.started_at = now
+    llm_task.finished_at = now
+    llm_task.params = {"dashboard_id": "42", "environment_id": "prod"}
+    llm_task.result = {"summary": "LLM validation complete"}
 
-        backup_task = MagicMock()
-        backup_task.id = "task-backup-1"
-        backup_task.plugin_id = "superset-backup"
-        backup_task.status = "RUNNING"
-        backup_task.started_at = now
-        backup_task.finished_at = None
-        backup_task.params = {"env": "prod", "dashboards": [42]}
-        backup_task.result = {}
+    backup_task = MagicMock()
+    backup_task.id = "task-backup-1"
+    backup_task.plugin_id = "superset-backup"
+    backup_task.status = "RUNNING"
+    backup_task.started_at = now
+    backup_task.finished_at = None
+    backup_task.params = {"env": "prod", "dashboards": [42]}
+    backup_task.result = {}
 
-        other_task = MagicMock()
-        other_task.id = "task-other"
-        other_task.plugin_id = "superset-backup"
-        other_task.status = "SUCCESS"
-        other_task.started_at = now
-        other_task.finished_at = now
-        other_task.params = {"env": "prod", "dashboards": [777]}
-        other_task.result = {}
+    other_task = MagicMock()
+    other_task.id = "task-other"
+    other_task.plugin_id = "superset-backup"
+    other_task.status = "SUCCESS"
+    other_task.started_at = now
+    other_task.finished_at = now
+    other_task.params = {"env": "prod", "dashboards": [777]}
+    other_task.result = {}
 
-        mock_task_mgr.return_value.get_all_tasks.return_value = [other_task, llm_task, backup_task]
-        mock_perm.return_value = lambda: True
+    mock_deps["task"].get_all_tasks.return_value = [other_task, llm_task, backup_task]
 
-        response = client.get("/api/dashboards/42/tasks?env_id=prod&limit=10")
+    response = client.get("/api/dashboards/42/tasks?env_id=prod&limit=10")
 
-        assert response.status_code == 200
-        data = response.json()
-        assert data["dashboard_id"] == 42
-        assert len(data["items"]) == 2
-        assert {item["plugin_id"] for item in data["items"]} == {"llm_dashboard_validation", "superset-backup"}
+    assert response.status_code == 200
+    data = response.json()
+    assert data["dashboard_id"] == 42
+    assert len(data["items"]) == 2
+    assert {item["plugin_id"] for item in data["items"]} == {"llm_dashboard_validation", "superset-backup"}
 # [/DEF:test_get_dashboard_tasks_history_filters_success:Function]
 
 
 # [DEF:test_get_dashboard_thumbnail_success:Function]
 # @TEST: GET /api/dashboards/{id}/thumbnail proxies image bytes from Superset
-def test_get_dashboard_thumbnail_success():
-    with patch("src.api.routes.dashboards.get_config_manager") as mock_config, \
-         patch("src.api.routes.dashboards.has_permission") as mock_perm, \
-         patch("src.api.routes.dashboards.SupersetClient") as mock_client_cls:
+def test_get_dashboard_thumbnail_success(mock_deps):
+    with patch("src.api.routes.dashboards.SupersetClient") as mock_client_cls:
         mock_env = MagicMock()
         mock_env.id = "prod"
-        mock_config.return_value.get_environments.return_value = [mock_env]
-        mock_perm.return_value = lambda: True
+        mock_deps["config"].get_environments.return_value = [mock_env]
 
         mock_client = MagicMock()
         mock_response = MagicMock()

backend/src/api/routes/__tests__/test_datasets.py

@@ -11,6 +11,41 @@ from unittest.mock import MagicMock, patch, AsyncMock
 from fastapi.testclient import TestClient
 from src.app import app
 from src.api.routes.datasets import DatasetsResponse, DatasetDetailResponse
+from src.dependencies import get_current_user, has_permission, get_config_manager, get_task_manager, get_resource_service, get_mapping_service
+
+# Global mock user for get_current_user dependency overrides
+mock_user = MagicMock()
+mock_user.username = "testuser"
+mock_user.roles = []
+admin_role = MagicMock()
+admin_role.name = "Admin"
+mock_user.roles.append(admin_role)
+
+@pytest.fixture(autouse=True)
+def mock_deps():
+    config_manager = MagicMock()
+    task_manager = MagicMock()
+    resource_service = MagicMock()
+    mapping_service = MagicMock()
+    
+    app.dependency_overrides[get_config_manager] = lambda: config_manager
+    app.dependency_overrides[get_task_manager] = lambda: task_manager
+    app.dependency_overrides[get_resource_service] = lambda: resource_service
+    app.dependency_overrides[get_mapping_service] = lambda: mapping_service
+    app.dependency_overrides[get_current_user] = lambda: mock_user
+    
+    app.dependency_overrides[has_permission("plugin:migration", "READ")] = lambda: mock_user
+    app.dependency_overrides[has_permission("plugin:migration", "EXECUTE")] = lambda: mock_user
+    app.dependency_overrides[has_permission("plugin:backup", "EXECUTE")] = lambda: mock_user
+    app.dependency_overrides[has_permission("tasks", "READ")] = lambda: mock_user
+    
+    yield {
+        "config": config_manager,
+        "task": task_manager,
+        "resource": resource_service,
+        "mapping": mapping_service
+    }
+    app.dependency_overrides.clear()
 
 client = TestClient(app)
 
@@ -20,41 +55,34 @@ client = TestClient(app)
 # @TEST: GET /api/datasets returns 200 and valid schema
 # @PRE: env_id exists
 # @POST: Response matches DatasetsResponse schema
-def test_get_datasets_success():
-    with patch("src.api.routes.datasets.get_config_manager") as mock_config, \
-         patch("src.api.routes.datasets.get_resource_service") as mock_service, \
-         patch("src.api.routes.datasets.has_permission") as mock_perm:
-        
-        # Mock environment
-        mock_env = MagicMock()
-        mock_env.id = "prod"
-        mock_config.return_value.get_environments.return_value = [mock_env]
-        
-        # Mock resource service response
-        mock_service.return_value.get_datasets_with_status.return_value = AsyncMock()(
-            return_value=[
-                {
-                    "id": 1,
-                    "table_name": "sales_data",
-                    "schema": "public",
-                    "database": "sales_db",
-                    "mapped_fields": {"total": 10, "mapped": 5},
-                    "last_task": {"task_id": "task-1", "status": "SUCCESS"}
-                }
-            ]
-        )
-        
-        # Mock permission
-        mock_perm.return_value = lambda: True
+def test_get_datasets_success(mock_deps):
+    # Mock environment
+    mock_env = MagicMock()
+    mock_env.id = "prod"
+    mock_deps["config"].get_environments.return_value = [mock_env]
+    
+    # Mock resource service response
+    mock_deps["resource"].get_datasets_with_status = AsyncMock(
+        return_value=[
+            {
+                "id": 1,
+                "table_name": "sales_data",
+                "schema": "public",
+                "database": "sales_db",
+                "mapped_fields": {"total": 10, "mapped": 5},
+                "last_task": {"task_id": "task-1", "status": "SUCCESS"}
+            }
+        ]
+    )
 
-        response = client.get("/api/datasets?env_id=prod")
-        
-        assert response.status_code == 200
-        data = response.json()
-        assert "datasets" in data
-        assert len(data["datasets"]) >= 0
-        # Validate against Pydantic model
-        DatasetsResponse(**data)
+    response = client.get("/api/datasets?env_id=prod")
+    
+    assert response.status_code == 200
+    data = response.json()
+    assert "datasets" in data
+    assert len(data["datasets"]) >= 0
+    # Validate against Pydantic model
+    DatasetsResponse(**data)
 
 
 # [/DEF:test_get_datasets_success:Function]
@@ -64,17 +92,13 @@ def test_get_datasets_success():
 # @TEST: GET /api/datasets returns 404 if env_id missing
 # @PRE: env_id does not exist
 # @POST: Returns 404 error
-def test_get_datasets_env_not_found():
-    with patch("src.api.routes.datasets.get_config_manager") as mock_config, \
-         patch("src.api.routes.datasets.has_permission") as mock_perm:
-        
-        mock_config.return_value.get_environments.return_value = []
-        mock_perm.return_value = lambda: True
+def test_get_datasets_env_not_found(mock_deps):
+    mock_deps["config"].get_environments.return_value = []
 
-        response = client.get("/api/datasets?env_id=nonexistent")
-        
-        assert response.status_code == 404
-        assert "Environment not found" in response.json()["detail"]
+    response = client.get("/api/datasets?env_id=nonexistent")
+    
+    assert response.status_code == 404
+    assert "Environment not found" in response.json()["detail"]
 
 
 # [/DEF:test_get_datasets_env_not_found:Function]
@@ -84,24 +108,25 @@ def test_get_datasets_env_not_found():
 # @TEST: GET /api/datasets returns 400 for invalid page/page_size
 # @PRE: page < 1 or page_size > 100
 # @POST: Returns 400 error
-def test_get_datasets_invalid_pagination():
-    with patch("src.api.routes.datasets.get_config_manager") as mock_config, \
-         patch("src.api.routes.datasets.has_permission") as mock_perm:
-        
-        mock_env = MagicMock()
-        mock_env.id = "prod"
-        mock_config.return_value.get_environments.return_value = [mock_env]
-        mock_perm.return_value = lambda: True
+def test_get_datasets_invalid_pagination(mock_deps):
+    mock_env = MagicMock()
+    mock_env.id = "prod"
+    mock_deps["config"].get_environments.return_value = [mock_env]
 
-        # Invalid page
-        response = client.get("/api/datasets?env_id=prod&page=0")
-        assert response.status_code == 400
-        assert "Page must be >= 1" in response.json()["detail"]
-        
-        # Invalid page_size
-        response = client.get("/api/datasets?env_id=prod&page_size=0")
-        assert response.status_code == 400
-        assert "Page size must be between 1 and 100" in response.json()["detail"]
+    # Invalid page
+    response = client.get("/api/datasets?env_id=prod&page=0")
+    assert response.status_code == 400
+    assert "Page must be >= 1" in response.json()["detail"]
+    
+    # Invalid page_size (too small)
+    response = client.get("/api/datasets?env_id=prod&page_size=0")
+    assert response.status_code == 400
+    assert "Page size must be between 1 and 100" in response.json()["detail"]
+
+    # @TEST_EDGE: page_size > 100 exceeds max
+    response = client.get("/api/datasets?env_id=prod&page_size=101")
+    assert response.status_code == 400
+    assert "Page size must be between 1 and 100" in response.json()["detail"]
 
 
 # [/DEF:test_get_datasets_invalid_pagination:Function]
@@ -111,36 +136,31 @@ def test_get_datasets_invalid_pagination():
 # @TEST: POST /api/datasets/map-columns creates mapping task
 # @PRE: Valid env_id, dataset_ids, source_type
 # @POST: Returns task_id
-def test_map_columns_success():
-    with patch("src.api.routes.datasets.get_config_manager") as mock_config, \
-         patch("src.api.routes.datasets.get_task_manager") as mock_task_mgr, \
-         patch("src.api.routes.datasets.has_permission") as mock_perm:
-        
-        # Mock environment
-        mock_env = MagicMock()
-        mock_env.id = "prod"
-        mock_config.return_value.get_environments.return_value = [mock_env]
-        
-        # Mock task manager
-        mock_task = MagicMock()
-        mock_task.id = "task-123"
-        mock_task_mgr.return_value.create_task = AsyncMock(return_value=mock_task)
-        
-        # Mock permission
-        mock_perm.return_value = lambda: True
+def test_map_columns_success(mock_deps):
+    # Mock environment
+    mock_env = MagicMock()
+    mock_env.id = "prod"
+    mock_deps["config"].get_environments.return_value = [mock_env]
+    
+    # Mock task manager
+    mock_task = MagicMock()
+    mock_task.id = "task-123"
+    mock_deps["task"].create_task = AsyncMock(return_value=mock_task)
 
-        response = client.post(
-            "/api/datasets/map-columns",
-            json={
-                "env_id": "prod",
-                "dataset_ids": [1, 2, 3],
-                "source_type": "postgresql"
-            }
-        )
-        
-        assert response.status_code == 200
-        data = response.json()
-        assert "task_id" in data
+    response = client.post(
+        "/api/datasets/map-columns",
+        json={
+            "env_id": "prod",
+            "dataset_ids": [1, 2, 3],
+            "source_type": "postgresql"
+        }
+    )
+    
+    assert response.status_code == 200
+    data = response.json()
+    assert "task_id" in data
+    # @POST/@SIDE_EFFECT: create_task was called
+    mock_deps["task"].create_task.assert_called_once()
 
 
 # [/DEF:test_map_columns_success:Function]
@@ -150,21 +170,18 @@ def test_map_columns_success():
 # @TEST: POST /api/datasets/map-columns returns 400 for invalid source_type
 # @PRE: source_type is not 'postgresql' or 'xlsx'
 # @POST: Returns 400 error
-def test_map_columns_invalid_source_type():
-    with patch("src.api.routes.datasets.has_permission") as mock_perm:
-        mock_perm.return_value = lambda: True
-
-        response = client.post(
-            "/api/datasets/map-columns",
-            json={
-                "env_id": "prod",
-                "dataset_ids": [1],
-                "source_type": "invalid"
-            }
-        )
-        
-        assert response.status_code == 400
-        assert "Source type must be 'postgresql' or 'xlsx'" in response.json()["detail"]
+def test_map_columns_invalid_source_type(mock_deps):
+    response = client.post(
+        "/api/datasets/map-columns",
+        json={
+            "env_id": "prod",
+            "dataset_ids": [1],
+            "source_type": "invalid"
+        }
+    )
+    
+    assert response.status_code == 400
+    assert "Source type must be 'postgresql' or 'xlsx'" in response.json()["detail"]
 
 
 # [/DEF:test_map_columns_invalid_source_type:Function]
@@ -174,39 +191,110 @@ def test_map_columns_invalid_source_type():
 # @TEST: POST /api/datasets/generate-docs creates doc generation task
 # @PRE: Valid env_id, dataset_ids, llm_provider
 # @POST: Returns task_id
-def test_generate_docs_success():
-    with patch("src.api.routes.datasets.get_config_manager") as mock_config, \
-         patch("src.api.routes.datasets.get_task_manager") as mock_task_mgr, \
-         patch("src.api.routes.datasets.has_permission") as mock_perm:
-        
-        # Mock environment
-        mock_env = MagicMock()
-        mock_env.id = "prod"
-        mock_config.return_value.get_environments.return_value = [mock_env]
-        
-        # Mock task manager
-        mock_task = MagicMock()
-        mock_task.id = "task-456"
-        mock_task_mgr.return_value.create_task = AsyncMock(return_value=mock_task)
-        
-        # Mock permission
-        mock_perm.return_value = lambda: True
+def test_generate_docs_success(mock_deps):
+    # Mock environment
+    mock_env = MagicMock()
+    mock_env.id = "prod"
+    mock_deps["config"].get_environments.return_value = [mock_env]
+    
+    # Mock task manager
+    mock_task = MagicMock()
+    mock_task.id = "task-456"
+    mock_deps["task"].create_task = AsyncMock(return_value=mock_task)
 
-        response = client.post(
-            "/api/datasets/generate-docs",
-            json={
-                "env_id": "prod",
-                "dataset_ids": [1],
-                "llm_provider": "openai"
-            }
-        )
-        
-        assert response.status_code == 200
-        data = response.json()
-        assert "task_id" in data
+    response = client.post(
+        "/api/datasets/generate-docs",
+        json={
+            "env_id": "prod",
+            "dataset_ids": [1],
+            "llm_provider": "openai"
+        }
+    )
+    
+    assert response.status_code == 200
+    data = response.json()
+    assert "task_id" in data
+    # @POST/@SIDE_EFFECT: create_task was called
+    mock_deps["task"].create_task.assert_called_once()
 
 
 # [/DEF:test_generate_docs_success:Function]
 
 
+# [DEF:test_map_columns_empty_ids:Function]
+# @TEST: POST /api/datasets/map-columns returns 400 for empty dataset_ids
+# @PRE: dataset_ids is empty
+# @POST: Returns 400 error
+def test_map_columns_empty_ids(mock_deps):
+    """@PRE: dataset_ids must be non-empty."""
+    response = client.post(
+        "/api/datasets/map-columns",
+        json={
+            "env_id": "prod",
+            "dataset_ids": [],
+            "source_type": "postgresql"
+        }
+    )
+    assert response.status_code == 400
+    assert "At least one dataset ID must be provided" in response.json()["detail"]
+# [/DEF:test_map_columns_empty_ids:Function]
+
+
+# [DEF:test_generate_docs_empty_ids:Function]
+# @TEST: POST /api/datasets/generate-docs returns 400 for empty dataset_ids
+# @PRE: dataset_ids is empty
+# @POST: Returns 400 error
+def test_generate_docs_empty_ids(mock_deps):
+    """@PRE: dataset_ids must be non-empty."""
+    response = client.post(
+        "/api/datasets/generate-docs",
+        json={
+            "env_id": "prod",
+            "dataset_ids": [],
+            "llm_provider": "openai"
+        }
+    )
+    assert response.status_code == 400
+    assert "At least one dataset ID must be provided" in response.json()["detail"]
+# [/DEF:test_generate_docs_empty_ids:Function]
+
+
+# [DEF:test_generate_docs_env_not_found:Function]
+# @TEST: POST /api/datasets/generate-docs returns 404 for missing env
+# @PRE: env_id does not exist
+# @POST: Returns 404 error
+def test_generate_docs_env_not_found(mock_deps):
+    """@PRE: env_id must be a valid environment."""
+    mock_deps["config"].get_environments.return_value = []
+    response = client.post(
+        "/api/datasets/generate-docs",
+        json={
+            "env_id": "ghost",
+            "dataset_ids": [1],
+            "llm_provider": "openai"
+        }
+    )
+    assert response.status_code == 404
+    assert "Environment not found" in response.json()["detail"]
+# [/DEF:test_generate_docs_env_not_found:Function]
+
+
+# [DEF:test_get_datasets_superset_failure:Function]
+# @TEST_EDGE: external_superset_failure -> {status: 503}
+def test_get_datasets_superset_failure(mock_deps):
+    """@TEST_EDGE: external_superset_failure -> {status: 503}"""
+    mock_env = MagicMock()
+    mock_env.id = "bad_conn"
+    mock_deps["config"].get_environments.return_value = [mock_env]
+    mock_deps["task"].get_all_tasks.return_value = []
+    mock_deps["resource"].get_datasets_with_status = AsyncMock(
+        side_effect=Exception("Connection refused")
+    )
+
+    response = client.get("/api/datasets?env_id=bad_conn")
+    assert response.status_code == 503
+    assert "Failed to fetch datasets" in response.json()["detail"]
+# [/DEF:test_get_datasets_superset_failure:Function]
+
+
 # [/DEF:backend.src.api.routes.__tests__.test_datasets:Module]

backend/src/api/routes/__tests__/test_git_status_route.py

@@ -0,0 +1,198 @@
+# [DEF:backend.src.api.routes.__tests__.test_git_status_route:Module]
+# @TIER: STANDARD
+# @SEMANTICS: tests, git, api, status, no_repo
+# @PURPOSE: Validate status endpoint behavior for missing and error repository states.
+# @LAYER: Domain (Tests)
+# @RELATION: CALLS -> src.api.routes.git.get_repository_status
+
+from fastapi import HTTPException
+import pytest
+import asyncio
+
+from src.api.routes import git as git_routes
+
+
+# [DEF:test_get_repository_status_returns_no_repo_payload_for_missing_repo:Function]
+# @PURPOSE: Ensure missing local repository is represented as NO_REPO payload instead of an API error.
+# @PRE: GitService.get_status raises HTTPException(404).
+# @POST: Route returns a deterministic NO_REPO status payload.
+def test_get_repository_status_returns_no_repo_payload_for_missing_repo(monkeypatch):
+    class MissingRepoGitService:
+        def _get_repo_path(self, dashboard_id: int) -> str:
+            return f"/tmp/missing-repo-{dashboard_id}"
+
+        def get_status(self, dashboard_id: int) -> dict:
+            raise AssertionError("get_status must not be called when repository path is missing")
+
+    monkeypatch.setattr(git_routes, "git_service", MissingRepoGitService())
+
+    response = asyncio.run(git_routes.get_repository_status(34))
+
+    assert response["sync_status"] == "NO_REPO"
+    assert response["sync_state"] == "NO_REPO"
+    assert response["has_repo"] is False
+    assert response["current_branch"] is None
+# [/DEF:test_get_repository_status_returns_no_repo_payload_for_missing_repo:Function]
+
+
+# [DEF:test_get_repository_status_propagates_non_404_http_exception:Function]
+# @PURPOSE: Ensure HTTP exceptions other than 404 are not masked.
+# @PRE: GitService.get_status raises HTTPException with non-404 status.
+# @POST: Raised exception preserves original status and detail.
+def test_get_repository_status_propagates_non_404_http_exception(monkeypatch):
+    class ConflictGitService:
+        def _get_repo_path(self, dashboard_id: int) -> str:
+            return f"/tmp/existing-repo-{dashboard_id}"
+
+        def get_status(self, dashboard_id: int) -> dict:
+            raise HTTPException(status_code=409, detail="Conflict")
+
+    monkeypatch.setattr(git_routes, "git_service", ConflictGitService())
+    monkeypatch.setattr(git_routes.os.path, "exists", lambda _path: True)
+
+    with pytest.raises(HTTPException) as exc_info:
+        asyncio.run(git_routes.get_repository_status(34))
+
+    assert exc_info.value.status_code == 409
+    assert exc_info.value.detail == "Conflict"
+# [/DEF:test_get_repository_status_propagates_non_404_http_exception:Function]
+
+
+# [DEF:test_get_repository_diff_propagates_http_exception:Function]
+# @PURPOSE: Ensure diff endpoint preserves domain HTTP errors from GitService.
+# @PRE: GitService.get_diff raises HTTPException.
+# @POST: Endpoint raises same HTTPException values.
+def test_get_repository_diff_propagates_http_exception(monkeypatch):
+    class DiffGitService:
+        def get_diff(self, dashboard_id: int, file_path=None, staged: bool = False) -> str:
+            raise HTTPException(status_code=404, detail="Repository missing")
+
+    monkeypatch.setattr(git_routes, "git_service", DiffGitService())
+
+    with pytest.raises(HTTPException) as exc_info:
+        asyncio.run(git_routes.get_repository_diff(12))
+
+    assert exc_info.value.status_code == 404
+    assert exc_info.value.detail == "Repository missing"
+# [/DEF:test_get_repository_diff_propagates_http_exception:Function]
+
+
+# [DEF:test_get_history_wraps_unexpected_error_as_500:Function]
+# @PURPOSE: Ensure non-HTTP exceptions in history endpoint become deterministic 500 errors.
+# @PRE: GitService.get_commit_history raises ValueError.
+# @POST: Endpoint returns HTTPException with status 500 and route context.
+def test_get_history_wraps_unexpected_error_as_500(monkeypatch):
+    class HistoryGitService:
+        def get_commit_history(self, dashboard_id: int, limit: int = 50):
+            raise ValueError("broken parser")
+
+    monkeypatch.setattr(git_routes, "git_service", HistoryGitService())
+
+    with pytest.raises(HTTPException) as exc_info:
+        asyncio.run(git_routes.get_history(12))
+
+    assert exc_info.value.status_code == 500
+    assert exc_info.value.detail == "get_history failed: broken parser"
+# [/DEF:test_get_history_wraps_unexpected_error_as_500:Function]
+
+
+# [DEF:test_commit_changes_wraps_unexpected_error_as_500:Function]
+# @PURPOSE: Ensure commit endpoint does not leak unexpected errors as 400.
+# @PRE: GitService.commit_changes raises RuntimeError.
+# @POST: Endpoint raises HTTPException(500) with route context.
+def test_commit_changes_wraps_unexpected_error_as_500(monkeypatch):
+    class CommitGitService:
+        def commit_changes(self, dashboard_id: int, message: str, files):
+            raise RuntimeError("index lock")
+
+    class CommitPayload:
+        message = "test"
+        files = ["dashboards/a.yaml"]
+
+    monkeypatch.setattr(git_routes, "git_service", CommitGitService())
+
+    with pytest.raises(HTTPException) as exc_info:
+        asyncio.run(git_routes.commit_changes(12, CommitPayload()))
+
+    assert exc_info.value.status_code == 500
+    assert exc_info.value.detail == "commit_changes failed: index lock"
+# [/DEF:test_commit_changes_wraps_unexpected_error_as_500:Function]
+
+
+# [DEF:test_get_repository_status_batch_returns_mixed_statuses:Function]
+# @PURPOSE: Ensure batch endpoint returns per-dashboard statuses in one response.
+# @PRE: Some repositories are missing and some are initialized.
+# @POST: Returned map includes resolved status for each requested dashboard ID.
+def test_get_repository_status_batch_returns_mixed_statuses(monkeypatch):
+    class BatchGitService:
+        def _get_repo_path(self, dashboard_id: int) -> str:
+            return f"/tmp/repo-{dashboard_id}"
+
+        def get_status(self, dashboard_id: int) -> dict:
+            if dashboard_id == 2:
+                return {"sync_state": "SYNCED", "sync_status": "OK"}
+            raise HTTPException(status_code=404, detail="not found")
+
+    monkeypatch.setattr(git_routes, "git_service", BatchGitService())
+    monkeypatch.setattr(git_routes.os.path, "exists", lambda path: path.endswith("/repo-2"))
+
+    class BatchRequest:
+        dashboard_ids = [1, 2]
+
+    response = asyncio.run(git_routes.get_repository_status_batch(BatchRequest()))
+
+    assert response.statuses["1"]["sync_status"] == "NO_REPO"
+    assert response.statuses["2"]["sync_state"] == "SYNCED"
+# [/DEF:test_get_repository_status_batch_returns_mixed_statuses:Function]
+
+
+# [DEF:test_get_repository_status_batch_marks_item_as_error_on_service_failure:Function]
+# @PURPOSE: Ensure batch endpoint marks failed items as ERROR without failing entire request.
+# @PRE: GitService raises non-HTTP exception for one dashboard.
+# @POST: Failed dashboard status is marked as ERROR.
+def test_get_repository_status_batch_marks_item_as_error_on_service_failure(monkeypatch):
+    class BatchErrorGitService:
+        def _get_repo_path(self, dashboard_id: int) -> str:
+            return f"/tmp/repo-{dashboard_id}"
+
+        def get_status(self, dashboard_id: int) -> dict:
+            raise RuntimeError("boom")
+
+    monkeypatch.setattr(git_routes, "git_service", BatchErrorGitService())
+    monkeypatch.setattr(git_routes.os.path, "exists", lambda _path: True)
+
+    class BatchRequest:
+        dashboard_ids = [9]
+
+    response = asyncio.run(git_routes.get_repository_status_batch(BatchRequest()))
+
+    assert response.statuses["9"]["sync_status"] == "ERROR"
+    assert response.statuses["9"]["sync_state"] == "ERROR"
+# [/DEF:test_get_repository_status_batch_marks_item_as_error_on_service_failure:Function]
+
+
+# [DEF:test_get_repository_status_batch_deduplicates_and_truncates_ids:Function]
+# @PURPOSE: Ensure batch endpoint protects server from oversized payloads.
+# @PRE: request includes duplicate IDs and more than MAX_REPOSITORY_STATUS_BATCH entries.
+# @POST: Result contains unique IDs up to configured cap.
+def test_get_repository_status_batch_deduplicates_and_truncates_ids(monkeypatch):
+    class SafeBatchGitService:
+        def _get_repo_path(self, dashboard_id: int) -> str:
+            return f"/tmp/repo-{dashboard_id}"
+
+        def get_status(self, dashboard_id: int) -> dict:
+            return {"sync_state": "SYNCED", "sync_status": "OK"}
+
+    monkeypatch.setattr(git_routes, "git_service", SafeBatchGitService())
+    monkeypatch.setattr(git_routes.os.path, "exists", lambda _path: True)
+
+    class BatchRequest:
+        dashboard_ids = [1, 1] + list(range(2, 90))
+
+    response = asyncio.run(git_routes.get_repository_status_batch(BatchRequest()))
+
+    assert len(response.statuses) == git_routes.MAX_REPOSITORY_STATUS_BATCH
+    assert "1" in response.statuses
+# [/DEF:test_get_repository_status_batch_deduplicates_and_truncates_ids:Function]
+
+# [/DEF:backend.src.api.routes.__tests__.test_git_status_route:Module]

backend/src/api/routes/__tests__/test_migration_routes.py

@@ -407,4 +407,104 @@ async def test_execute_migration_invalid_env_raises_400(_mock_env):
     assert exc.value.status_code == 400
 
 
+@pytest.mark.asyncio
+async def test_dry_run_migration_returns_diff_and_risk(db_session):
+    # @TEST_EDGE: missing_target_datasource -> validates high risk item generation
+    # @TEST_EDGE: breaking_reference -> validates high risk on missing dataset link
+    from src.api.routes.migration import dry_run_migration
+    from src.models.dashboard import DashboardSelection
+
+    env_source = MagicMock()
+    env_source.id = "src"
+    env_source.name = "Source"
+    env_source.url = "http://source"
+    env_source.username = "admin"
+    env_source.password = "admin"
+    env_source.verify_ssl = False
+    env_source.timeout = 30
+
+    env_target = MagicMock()
+    env_target.id = "tgt"
+    env_target.name = "Target"
+    env_target.url = "http://target"
+    env_target.username = "admin"
+    env_target.password = "admin"
+    env_target.verify_ssl = False
+    env_target.timeout = 30
+
+    cm = _make_sync_config_manager([env_source, env_target])
+    selection = DashboardSelection(
+        selected_ids=[42],
+        source_env_id="src",
+        target_env_id="tgt",
+        replace_db_config=False,
+        fix_cross_filters=True,
+    )
+
+    with patch("src.api.routes.migration.SupersetClient") as MockClient, \
+         patch("src.api.routes.migration.MigrationDryRunService") as MockService:
+        source_client = MagicMock()
+        target_client = MagicMock()
+        MockClient.side_effect = [source_client, target_client]
+
+        service_instance = MagicMock()
+        service_payload = {
+            "generated_at": "2026-02-27T00:00:00+00:00",
+            "selection": selection.model_dump(),
+            "selected_dashboard_titles": ["Sales"],
+            "diff": {
+                "dashboards": {"create": [], "update": [{"uuid": "dash-1"}], "delete": []},
+                "charts": {"create": [{"uuid": "chart-1"}], "update": [], "delete": []},
+                "datasets": {"create": [{"uuid": "dataset-1"}], "update": [], "delete": []},
+            },
+            "summary": {
+                "dashboards": {"create": 0, "update": 1, "delete": 0},
+                "charts": {"create": 1, "update": 0, "delete": 0},
+                "datasets": {"create": 1, "update": 0, "delete": 0},
+                "selected_dashboards": 1,
+            },
+            "risk": {
+                "score": 75,
+                "level": "high",
+                "items": [
+                    {"code": "missing_datasource"},
+                    {"code": "breaking_reference"},
+                ],
+            },
+        }
+        service_instance.run.return_value = service_payload
+        MockService.return_value = service_instance
+
+        result = await dry_run_migration(selection=selection, config_manager=cm, db=db_session, _=None)
+
+    assert result["summary"]["dashboards"]["update"] == 1
+    assert result["summary"]["charts"]["create"] == 1
+    assert result["summary"]["datasets"]["create"] == 1
+    assert result["risk"]["score"] > 0
+    assert any(item["code"] == "missing_datasource" for item in result["risk"]["items"])
+    assert any(item["code"] == "breaking_reference" for item in result["risk"]["items"])
+
+
+@pytest.mark.asyncio
+async def test_dry_run_migration_rejects_same_environment(db_session):
+    from src.api.routes.migration import dry_run_migration
+    from src.models.dashboard import DashboardSelection
+
+    env = MagicMock()
+    env.id = "same"
+    env.name = "Same"
+    env.url = "http://same"
+    env.username = "admin"
+    env.password = "admin"
+    env.verify_ssl = False
+    env.timeout = 30
+
+    cm = _make_sync_config_manager([env])
+    selection = DashboardSelection(selected_ids=[1], source_env_id="same", target_env_id="same")
+
+    with pytest.raises(HTTPException) as exc:
+        await dry_run_migration(selection=selection, config_manager=cm, db=db_session, _=None)
+    assert exc.value.status_code == 400
+
+
 # [/DEF:backend.src.api.routes.__tests__.test_migration_routes:Module]

backend/src/api/routes/assistant.py

@@ -810,6 +810,9 @@ def _parse_command(message: str, config_manager: ConfigManager) -> Dict[str, Any
     if any(k in lower for k in ["миграц", "migration", "migrate"]):
         src = _extract_id(lower, [r"(?:с|from)\s+([a-z0-9_-]+)"])
         tgt = _extract_id(lower, [r"(?:на|to)\s+([a-z0-9_-]+)"])
+        dry_run = "--dry-run" in lower or "dry run" in lower
+        replace_db_config = "--replace-db-config" in lower
+        fix_cross_filters = "--fix-cross-filters" not in lower  # Default true usually, but let's say test uses --dry-run
         is_dangerous = _is_production_env(tgt, config_manager)
         return {
             "domain": "migration",
@@ -818,10 +821,13 @@ def _parse_command(message: str, config_manager: ConfigManager) -> Dict[str, Any
                 "dashboard_id": int(dashboard_id) if dashboard_id else None,
                 "source_env": src,
                 "target_env": tgt,
+                "dry_run": dry_run,
+                "replace_db_config": replace_db_config,
+                "fix_cross_filters": True,
             },
             "confidence": 0.95 if dashboard_id and src and tgt else 0.72,
             "risk_level": "dangerous" if is_dangerous else "guarded",
-            "requires_confirmation": is_dangerous,
+            "requires_confirmation": is_dangerous or dry_run,
         }
 
     # Backup
@@ -1057,7 +1063,7 @@ _SAFE_OPS = {"show_capabilities", "get_task_status"}
 # @PURPOSE: Build human-readable confirmation prompt for an intent before execution.
 # @PRE: intent contains operation and entities fields.
 # @POST: Returns descriptive Russian-language text ending with confirmation prompt.
-def _confirmation_summary(intent: Dict[str, Any]) -> str:
+async def _async_confirmation_summary(intent: Dict[str, Any], config_manager: ConfigManager, db: Session) -> str:
     operation = intent.get("operation", "")
     entities = intent.get("entities", {})
     descriptions: Dict[str, str] = {
@@ -1085,8 +1091,67 @@ def _confirmation_summary(intent: Dict[str, Any]) -> str:
         tgt=_label(entities.get("target_env")),
         dataset=_label(entities.get("dataset_id")),
     )
+
+    if operation == "execute_migration":
+        flags = []
+        flags.append("маппинг БД: " + ("ВКЛ" if _coerce_query_bool(entities.get("replace_db_config", False)) else "ВЫКЛ"))
+        flags.append("исправление кроссфильтров: " + ("ВКЛ" if _coerce_query_bool(entities.get("fix_cross_filters", True)) else "ВЫКЛ"))
+        dry_run_enabled = _coerce_query_bool(entities.get("dry_run", False))
+        flags.append("отчет dry-run: " + ("ВКЛ" if dry_run_enabled else "ВЫКЛ"))
+        text += f" ({', '.join(flags)})"
+
+        if dry_run_enabled:
+            try:
+                from ...core.migration.dry_run_orchestrator import MigrationDryRunService
+                from ...models.dashboard import DashboardSelection
+                from ...core.superset_client import SupersetClient
+                
+                src_token = entities.get("source_env")
+                tgt_token = entities.get("target_env")
+                dashboard_id = _resolve_dashboard_id_entity(entities, config_manager, env_hint=src_token)
+                
+                if dashboard_id and src_token and tgt_token:
+                    src_env_id = _resolve_env_id(src_token, config_manager)
+                    tgt_env_id = _resolve_env_id(tgt_token, config_manager)
+                    
+                    if src_env_id and tgt_env_id:
+                        env_map = {env.id: env for env in config_manager.get_environments()}
+                        source_env = env_map.get(src_env_id)
+                        target_env = env_map.get(tgt_env_id)
+                        
+                        if source_env and target_env and source_env.id != target_env.id:
+                            selection = DashboardSelection(
+                                source_env_id=source_env.id,
+                                target_env_id=target_env.id,
+                                selected_ids=[dashboard_id],
+                                replace_db_config=_coerce_query_bool(entities.get("replace_db_config", False)),
+                                fix_cross_filters=_coerce_query_bool(entities.get("fix_cross_filters", True))
+                            )
+                            service = MigrationDryRunService()
+                            source_client = SupersetClient(source_env)
+                            target_client = SupersetClient(target_env)
+                            report = service.run(selection, source_client, target_client, db)
+                            
+                            s = report.get("summary", {})
+                            dash_s = s.get("dashboards", {})
+                            charts_s = s.get("charts", {})
+                            ds_s = s.get("datasets", {})
+                            
+                            # Determine main actions counts
+                            creates = dash_s.get("create", 0) + charts_s.get("create", 0) + ds_s.get("create", 0)
+                            updates = dash_s.get("update", 0) + charts_s.get("update", 0) + ds_s.get("update", 0)
+                            deletes = dash_s.get("delete", 0) + charts_s.get("delete", 0) + ds_s.get("delete", 0)
+                            
+                            text += f"\n\nОтчет dry-run:\n- Будет создано новых объектов: {creates}\n- Будет обновлено: {updates}\n- Будет удалено: {deletes}"
+                        else:
+                            text += "\n\n(Не удалось загрузить отчет dry-run: неверные окружения)."
+            except Exception as e:
+                import traceback
+                logger.warning("[assistant.dry_run_summary][failed] Exception: %s\n%s", e, traceback.format_exc())
+                text += f"\n\n(Не удалось загрузить отчет dry-run: {e})."
+
     return f"Выполнить: {text}. Подтвердите или отмените."
-# [/DEF:_confirmation_summary:Function]
+# [/DEF:_async_confirmation_summary:Function]
 
 
 # [DEF:_clarification_text_for_intent:Function]
@@ -1176,7 +1241,8 @@ async def _plan_intent_with_llm(
             ]
         )
     except Exception as exc:
-        logger.warning(f"[assistant.planner][fallback] LLM planner unavailable: {exc}")
+        import traceback
+        logger.warning(f"[assistant.planner][fallback] LLM planner unavailable: {exc}\n{traceback.format_exc()}")
         return None
     if not isinstance(response, dict):
         return None
@@ -1580,7 +1646,7 @@ async def send_message(
                 )
                 CONFIRMATIONS[confirmation_id] = confirm
                 _persist_confirmation(db, confirm)
-                text = _confirmation_summary(intent)
+                text = await _async_confirmation_summary(intent, config_manager, db)
                 _append_history(
                     user_id,
                     conversation_id,
@@ -1895,6 +1961,39 @@ async def list_conversations(
 # [/DEF:list_conversations:Function]
 
 
+# [DEF:delete_conversation:Function]
+# @PURPOSE: Soft-delete or hard-delete a conversation and clear its in-memory trace.
+# @PRE: conversation_id belongs to current_user.
+# @POST: Conversation records are removed from DB and CONVERSATIONS cache.
+@router.delete("/conversations/{conversation_id}")
+async def delete_conversation(
+    conversation_id: str,
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    with belief_scope("assistant.conversations.delete"):
+        user_id = current_user.id
+        
+        # 1. Remove from in-memory cache
+        key = (user_id, conversation_id)
+        if key in CONVERSATIONS:
+            del CONVERSATIONS[key]
+            
+        # 2. Delete from database
+        deleted_count = db.query(AssistantMessageRecord).filter(
+            AssistantMessageRecord.user_id == user_id,
+            AssistantMessageRecord.conversation_id == conversation_id
+        ).delete()
+        
+        db.commit()
+        
+        if deleted_count == 0:
+            raise HTTPException(status_code=404, detail="Conversation not found or already deleted")
+            
+        return {"status": "success", "deleted": deleted_count, "conversation_id": conversation_id}
+# [/DEF:delete_conversation:Function]
+
+
 @router.get("/history")
 # [DEF:get_history:Function]
 # @PURPOSE: Retrieve paginated assistant conversation history for current user.

backend/src/api/routes/clean_release.py

@@ -0,0 +1,185 @@
+# [DEF:backend.src.api.routes.clean_release:Module]
+# @TIER: STANDARD
+# @SEMANTICS: api, clean-release, candidate-preparation, compliance
+# @PURPOSE: Expose clean release endpoints for candidate preparation and subsequent compliance flow.
+# @LAYER: API
+# @RELATION: DEPENDS_ON -> backend.src.dependencies.get_clean_release_repository
+# @RELATION: DEPENDS_ON -> backend.src.services.clean_release.preparation_service
+# @INVARIANT: API never reports prepared status if preparation errors are present.
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any, Dict, List
+
+from fastapi import APIRouter, Depends, HTTPException, status
+from pydantic import BaseModel, Field
+
+from ...core.logger import belief_scope, logger
+from ...dependencies import get_clean_release_repository
+from ...services.clean_release.preparation_service import prepare_candidate
+from ...services.clean_release.repository import CleanReleaseRepository
+from ...services.clean_release.compliance_orchestrator import CleanComplianceOrchestrator
+from ...services.clean_release.report_builder import ComplianceReportBuilder
+from ...models.clean_release import (
+    CheckFinalStatus,
+    CheckStageName,
+    CheckStageResult,
+    CheckStageStatus,
+    ComplianceViolation,
+    ViolationCategory,
+    ViolationSeverity,
+)
+
+router = APIRouter(prefix="/api/clean-release", tags=["Clean Release"])
+
+
+# [DEF:PrepareCandidateRequest:Class]
+# @PURPOSE: Request schema for candidate preparation endpoint.
+class PrepareCandidateRequest(BaseModel):
+    candidate_id: str = Field(min_length=1)
+    artifacts: List[Dict[str, Any]] = Field(default_factory=list)
+    sources: List[str] = Field(default_factory=list)
+    operator_id: str = Field(min_length=1)
+# [/DEF:PrepareCandidateRequest:Class]
+
+
+# [DEF:StartCheckRequest:Class]
+# @PURPOSE: Request schema for clean compliance check run startup.
+class StartCheckRequest(BaseModel):
+    candidate_id: str = Field(min_length=1)
+    profile: str = Field(default="enterprise-clean")
+    execution_mode: str = Field(default="tui")
+    triggered_by: str = Field(default="system")
+# [/DEF:StartCheckRequest:Class]
+
+
+# [DEF:prepare_candidate_endpoint:Function]
+# @PURPOSE: Prepare candidate with policy evaluation and deterministic manifest generation.
+# @PRE: Candidate and active policy exist in repository.
+# @POST: Returns preparation result including manifest reference and violations.
+@router.post("/candidates/prepare")
+async def prepare_candidate_endpoint(
+    payload: PrepareCandidateRequest,
+    repository: CleanReleaseRepository = Depends(get_clean_release_repository),
+):
+    try:
+        result = prepare_candidate(
+            repository=repository,
+            candidate_id=payload.candidate_id,
+            artifacts=payload.artifacts,
+            sources=payload.sources,
+            operator_id=payload.operator_id,
+        )
+        return result
+    except ValueError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail={"message": str(exc), "code": "CLEAN_PREPARATION_ERROR"},
+        )
+# [/DEF:prepare_candidate_endpoint:Function]
+
+
+# [DEF:start_check:Function]
+# @PURPOSE: Start and finalize a clean compliance check run and persist report artifacts.
+# @PRE: Active policy and candidate exist.
+# @POST: Returns accepted payload with check_run_id and started_at.
+@router.post("/checks", status_code=status.HTTP_202_ACCEPTED)
+async def start_check(
+    payload: StartCheckRequest,
+    repository: CleanReleaseRepository = Depends(get_clean_release_repository),
+):
+    with belief_scope("clean_release.start_check"):
+        logger.reason("Starting clean-release compliance check run")
+        policy = repository.get_active_policy()
+        if policy is None:
+            raise HTTPException(status_code=409, detail={"message": "Active policy not found", "code": "POLICY_NOT_FOUND"})
+
+        candidate = repository.get_candidate(payload.candidate_id)
+        if candidate is None:
+            raise HTTPException(status_code=409, detail={"message": "Candidate not found", "code": "CANDIDATE_NOT_FOUND"})
+
+        orchestrator = CleanComplianceOrchestrator(repository)
+        run = orchestrator.start_check_run(
+            candidate_id=payload.candidate_id,
+            policy_id=policy.policy_id,
+            triggered_by=payload.triggered_by,
+            execution_mode=payload.execution_mode,
+        )
+
+        forced = [
+            CheckStageResult(stage=CheckStageName.DATA_PURITY, status=CheckStageStatus.PASS, details="ok"),
+            CheckStageResult(stage=CheckStageName.INTERNAL_SOURCES_ONLY, status=CheckStageStatus.PASS, details="ok"),
+            CheckStageResult(stage=CheckStageName.NO_EXTERNAL_ENDPOINTS, status=CheckStageStatus.PASS, details="ok"),
+            CheckStageResult(stage=CheckStageName.MANIFEST_CONSISTENCY, status=CheckStageStatus.PASS, details="ok"),
+        ]
+        run = orchestrator.execute_stages(run, forced_results=forced)
+        run = orchestrator.finalize_run(run)
+
+        if run.final_status == CheckFinalStatus.BLOCKED:
+            logger.explore("Run ended as BLOCKED, persisting synthetic external-source violation")
+            violation = ComplianceViolation(
+                violation_id=f"viol-{run.check_run_id}",
+                check_run_id=run.check_run_id,
+                category=ViolationCategory.EXTERNAL_SOURCE,
+                severity=ViolationSeverity.CRITICAL,
+                location="external.example.com",
+                remediation="Replace with approved internal server",
+                blocked_release=True,
+                detected_at=datetime.now(timezone.utc),
+            )
+            repository.save_violation(violation)
+
+        builder = ComplianceReportBuilder(repository)
+        report = builder.build_report_payload(run, repository.get_violations_by_check_run(run.check_run_id))
+        builder.persist_report(report)
+        logger.reflect(f"Compliance report persisted for check_run_id={run.check_run_id}")
+
+        return {
+            "check_run_id": run.check_run_id,
+            "candidate_id": run.candidate_id,
+            "status": "running",
+            "started_at": run.started_at.isoformat(),
+        }
+# [/DEF:start_check:Function]
+
+
+# [DEF:get_check_status:Function]
+# @PURPOSE: Return terminal/intermediate status payload for a check run.
+# @PRE: check_run_id references an existing run.
+# @POST: Deterministic payload shape includes checks and violations arrays.
+@router.get("/checks/{check_run_id}")
+async def get_check_status(check_run_id: str, repository: CleanReleaseRepository = Depends(get_clean_release_repository)):
+    with belief_scope("clean_release.get_check_status"):
+        run = repository.get_check_run(check_run_id)
+        if run is None:
+            raise HTTPException(status_code=404, detail={"message": "Check run not found", "code": "CHECK_NOT_FOUND"})
+
+        logger.reflect(f"Returning check status for check_run_id={check_run_id}")
+        return {
+            "check_run_id": run.check_run_id,
+            "candidate_id": run.candidate_id,
+            "final_status": run.final_status.value,
+            "started_at": run.started_at.isoformat(),
+            "finished_at": run.finished_at.isoformat() if run.finished_at else None,
+            "checks": [c.model_dump() for c in run.checks],
+            "violations": [v.model_dump() for v in repository.get_violations_by_check_run(check_run_id)],
+        }
+# [/DEF:get_check_status:Function]
+
+
+# [DEF:get_report:Function]
+# @PURPOSE: Return persisted compliance report by report_id.
+# @PRE: report_id references an existing report.
+# @POST: Returns serialized report object.
+@router.get("/reports/{report_id}")
+async def get_report(report_id: str, repository: CleanReleaseRepository = Depends(get_clean_release_repository)):
+    with belief_scope("clean_release.get_report"):
+        report = repository.get_report(report_id)
+        if report is None:
+            raise HTTPException(status_code=404, detail={"message": "Report not found", "code": "REPORT_NOT_FOUND"})
+
+        logger.reflect(f"Returning compliance report report_id={report_id}")
+        return report.model_dump()
+# [/DEF:get_report:Function]
+# [/DEF:backend.src.api.routes.clean_release:Module]

backend/src/api/routes/dashboards.py

@@ -1,6 +1,6 @@
 # [DEF:backend.src.api.routes.dashboards:Module]
 #
-# @TIER: STANDARD
+# @TIER: CRITICAL
 # @SEMANTICS: api, dashboards, resources, hub
 # @PURPOSE:   API endpoints for the Dashboard Hub - listing dashboards with Git and task status
 # @LAYER:     API
@@ -9,6 +9,27 @@
 # @RELATION:  DEPENDS_ON -> backend.src.core.superset_client
 #
 # @INVARIANT: All dashboard responses include git_status and last_task metadata
+#
+# @TEST_CONTRACT: DashboardsAPI -> {
+#    required_fields: {env_id: string, page: integer, page_size: integer},
+#    optional_fields: {search: string},
+#    invariants: ["Pagination must be valid", "Environment must exist"]
+# }
+#
+# @TEST_FIXTURE: dashboard_list_happy -> {
+#    "env_id": "prod",
+#    "expected_count": 1,
+#    "dashboards": [{"id": 1, "title": "Main Revenue"}]
+# }
+#
+# @TEST_EDGE: pagination_zero_page -> {"env_id": "prod", "page": 0, "status": 400}
+# @TEST_EDGE: pagination_oversize -> {"env_id": "prod", "page_size": 101, "status": 400}
+# @TEST_EDGE: missing_env -> {"env_id": "ghost", "status": 404}
+# @TEST_EDGE: empty_dashboards -> {"env_id": "empty_env", "expected_total": 0}
+# @TEST_EDGE: external_superset_failure -> {"env_id": "bad_conn", "status": 503}
+#
+# @TEST_INVARIANT: metadata_consistency -> verifies: [dashboard_list_happy, empty_dashboards]
+#
 
 # [SECTION: IMPORTS]
 from fastapi import APIRouter, Depends, HTTPException, Query, Response
@@ -21,6 +42,7 @@ from ...dependencies import get_config_manager, get_task_manager, get_resource_s
 from ...core.logger import logger, belief_scope
 from ...core.superset_client import SupersetClient
 from ...core.utils.network import DashboardNotFoundError
+from ...services.resource_service import ResourceService
 # [/SECTION]
 
 router = APIRouter(prefix="/api/dashboards", tags=["Dashboards"])
@@ -36,7 +58,11 @@ class GitStatus(BaseModel):
 # [DEF:LastTask:DataClass]
 class LastTask(BaseModel):
     task_id: Optional[str] = None
-    status: Optional[str] = Field(None, pattern="^RUNNING|SUCCESS|ERROR|WAITING_INPUT$")
+    status: Optional[str] = Field(
+        None,
+        pattern="^PENDING|RUNNING|SUCCESS|FAILED|ERROR|AWAITING_INPUT|WAITING_INPUT|AWAITING_MAPPING$",
+    )
+    validation_status: Optional[str] = Field(None, pattern="^PASS|FAIL|WARN|UNKNOWN$")
 # [/DEF:LastTask:DataClass]
 
 # [DEF:DashboardItem:DataClass]
@@ -46,6 +72,9 @@ class DashboardItem(BaseModel):
     slug: Optional[str] = None
     url: Optional[str] = None
     last_modified: Optional[str] = None
+    created_by: Optional[str] = None
+    modified_by: Optional[str] = None
+    owners: Optional[List[str]] = None
     git_status: Optional[GitStatus] = None
     last_task: Optional[LastTask] = None
 # [/DEF:DashboardItem:DataClass]
@@ -126,6 +155,93 @@ class DatabaseMappingsResponse(BaseModel):
     mappings: List[DatabaseMapping]
 # [/DEF:DatabaseMappingsResponse:DataClass]
 
+
+# [DEF:_find_dashboard_id_by_slug:Function]
+# @PURPOSE: Resolve dashboard numeric ID by slug using Superset list endpoint.
+# @PRE: `dashboard_slug` is non-empty.
+# @POST: Returns dashboard ID when found, otherwise None.
+def _find_dashboard_id_by_slug(
+    client: SupersetClient,
+    dashboard_slug: str,
+) -> Optional[int]:
+    query_variants = [
+        {"filters": [{"col": "slug", "opr": "eq", "value": dashboard_slug}], "page": 0, "page_size": 1},
+        {"filters": [{"col": "slug", "op": "eq", "value": dashboard_slug}], "page": 0, "page_size": 1},
+    ]
+
+    for query in query_variants:
+        try:
+            _count, dashboards = client.get_dashboards_page(query=query)
+            if dashboards:
+                resolved_id = dashboards[0].get("id")
+                if resolved_id is not None:
+                    return int(resolved_id)
+        except Exception:
+            continue
+
+    return None
+# [/DEF:_find_dashboard_id_by_slug:Function]
+
+
+# [DEF:_resolve_dashboard_id_from_ref:Function]
+# @PURPOSE: Resolve dashboard ID from slug-first reference with numeric fallback.
+# @PRE: `dashboard_ref` is provided in route path.
+# @POST: Returns a valid dashboard ID or raises HTTPException(404).
+def _resolve_dashboard_id_from_ref(
+    dashboard_ref: str,
+    client: SupersetClient,
+) -> int:
+    normalized_ref = str(dashboard_ref or "").strip()
+    if not normalized_ref:
+        raise HTTPException(status_code=404, detail="Dashboard not found")
+
+    # Slug-first: even if ref looks numeric, try slug first.
+    slug_match_id = _find_dashboard_id_by_slug(client, normalized_ref)
+    if slug_match_id is not None:
+        return slug_match_id
+
+    if normalized_ref.isdigit():
+        return int(normalized_ref)
+
+    raise HTTPException(status_code=404, detail="Dashboard not found")
+# [/DEF:_resolve_dashboard_id_from_ref:Function]
+
+
+# [DEF:_normalize_filter_values:Function]
+# @PURPOSE: Normalize query filter values to lower-cased non-empty tokens.
+# @PRE: values may be None or list of strings.
+# @POST: Returns trimmed normalized list preserving input order.
+def _normalize_filter_values(values: Optional[List[str]]) -> List[str]:
+    if not values:
+        return []
+    normalized: List[str] = []
+    for value in values:
+        token = str(value or "").strip().lower()
+        if token:
+            normalized.append(token)
+    return normalized
+# [/DEF:_normalize_filter_values:Function]
+
+
+# [DEF:_dashboard_git_filter_value:Function]
+# @PURPOSE: Build comparable git status token for dashboards filtering.
+# @PRE: dashboard payload may contain git_status or None.
+# @POST: Returns one of ok|diff|no_repo|error|pending.
+def _dashboard_git_filter_value(dashboard: Dict[str, Any]) -> str:
+    git_status = dashboard.get("git_status") or {}
+    sync_status = str(git_status.get("sync_status") or "").strip().upper()
+    has_repo = git_status.get("has_repo")
+    if has_repo is False or sync_status == "NO_REPO":
+        return "no_repo"
+    if sync_status == "DIFF":
+        return "diff"
+    if sync_status == "OK":
+        return "ok"
+    if sync_status == "ERROR":
+        return "error"
+    return "pending"
+# [/DEF:_dashboard_git_filter_value:Function]
+
 # [DEF:get_dashboards:Function]
 # @PURPOSE: Fetch list of dashboards from a specific environment with Git status and last task status
 # @PRE: env_id must be a valid environment ID
@@ -145,6 +261,11 @@ async def get_dashboards(
     search: Optional[str] = None,
     page: int = 1,
     page_size: int = 10,
+    filter_title: Optional[List[str]] = Query(default=None),
+    filter_git_status: Optional[List[str]] = Query(default=None),
+    filter_llm_status: Optional[List[str]] = Query(default=None),
+    filter_changed_on: Optional[List[str]] = Query(default=None),
+    filter_actor: Optional[List[str]] = Query(default=None),
     config_manager=Depends(get_config_manager),
     task_manager=Depends(get_task_manager),
     resource_service=Depends(get_resource_service),
@@ -169,27 +290,134 @@ async def get_dashboards(
         try:
             # Get all tasks for status lookup
             all_tasks = task_manager.get_all_tasks()
-            
-            # Fetch dashboards with status using ResourceService
-            dashboards = await resource_service.get_dashboards_with_status(env, all_tasks)
-            
-            # Apply search filter if provided
-            if search:
-                search_lower = search.lower()
-                dashboards = [
-                    d for d in dashboards 
-                    if search_lower in d.get('title', '').lower() 
-                    or search_lower in d.get('slug', '').lower()
-                ]
-            
-            # Calculate pagination
-            total = len(dashboards)
-            total_pages = (total + page_size - 1) // page_size if total > 0 else 1
-            start_idx = (page - 1) * page_size
-            end_idx = start_idx + page_size
-            
-            # Slice dashboards for current page
-            paginated_dashboards = dashboards[start_idx:end_idx]
+            title_filters = _normalize_filter_values(filter_title)
+            git_filters = _normalize_filter_values(filter_git_status)
+            llm_filters = _normalize_filter_values(filter_llm_status)
+            changed_on_filters = _normalize_filter_values(filter_changed_on)
+            actor_filters = _normalize_filter_values(filter_actor)
+            has_column_filters = any(
+                (
+                    title_filters,
+                    git_filters,
+                    llm_filters,
+                    changed_on_filters,
+                    actor_filters,
+                )
+            )
+
+            # Fast path: real ResourceService -> one Superset page call per API request.
+            if isinstance(resource_service, ResourceService) and not has_column_filters:
+                try:
+                    page_payload = await resource_service.get_dashboards_page_with_status(
+                        env,
+                        all_tasks,
+                        page=page,
+                        page_size=page_size,
+                        search=search,
+                        include_git_status=False,
+                    )
+                    paginated_dashboards = page_payload["dashboards"]
+                    total = page_payload["total"]
+                    total_pages = page_payload["total_pages"]
+                except Exception as page_error:
+                    logger.warning(
+                        "[get_dashboards][Action] Page-based fetch failed; using compatibility fallback: %s",
+                        page_error,
+                    )
+                    dashboards = await resource_service.get_dashboards_with_status(
+                        env,
+                        all_tasks,
+                        include_git_status=False,
+                    )
+
+                    if search:
+                        search_lower = search.lower()
+                        dashboards = [
+                            d for d in dashboards 
+                            if search_lower in d.get('title', '').lower() 
+                            or search_lower in d.get('slug', '').lower()
+                        ]
+
+                    total = len(dashboards)
+                    total_pages = (total + page_size - 1) // page_size if total > 0 else 1
+                    start_idx = (page - 1) * page_size
+                    end_idx = start_idx + page_size
+                    paginated_dashboards = dashboards[start_idx:end_idx]
+            elif isinstance(resource_service, ResourceService) and has_column_filters:
+                dashboards = await resource_service.get_dashboards_with_status(
+                    env,
+                    all_tasks,
+                    include_git_status=bool(git_filters),
+                )
+
+                if search:
+                    search_lower = search.lower()
+                    dashboards = [
+                        d for d in dashboards
+                        if search_lower in d.get("title", "").lower()
+                        or search_lower in d.get("slug", "").lower()
+                    ]
+
+                def _matches_dashboard_filters(dashboard: Dict[str, Any]) -> bool:
+                    title_value = str(dashboard.get("title") or "").strip().lower()
+                    if title_filters and title_value not in title_filters:
+                        return False
+
+                    if git_filters:
+                        git_value = _dashboard_git_filter_value(dashboard)
+                        if git_value not in git_filters:
+                            return False
+
+                    llm_value = str(
+                        ((dashboard.get("last_task") or {}).get("validation_status"))
+                        or "UNKNOWN"
+                    ).strip().lower()
+                    if llm_filters and llm_value not in llm_filters:
+                        return False
+
+                    changed_on_raw = str(dashboard.get("last_modified") or "").strip().lower()
+                    changed_on_prefix = changed_on_raw[:10] if len(changed_on_raw) >= 10 else changed_on_raw
+                    if changed_on_filters and changed_on_raw not in changed_on_filters and changed_on_prefix not in changed_on_filters:
+                        return False
+
+                    owners = dashboard.get("owners") or []
+                    if isinstance(owners, list):
+                        actor_value = ", ".join(str(item).strip() for item in owners if str(item).strip()).lower()
+                    else:
+                        actor_value = str(owners).strip().lower()
+                    if not actor_value:
+                        actor_value = "-"
+                    if actor_filters and actor_value not in actor_filters:
+                        return False
+                    return True
+
+                dashboards = [d for d in dashboards if _matches_dashboard_filters(d)]
+                total = len(dashboards)
+                total_pages = (total + page_size - 1) // page_size if total > 0 else 1
+                start_idx = (page - 1) * page_size
+                end_idx = start_idx + page_size
+                paginated_dashboards = dashboards[start_idx:end_idx]
+            else:
+                # Compatibility path for mocked services in route tests.
+                dashboards = await resource_service.get_dashboards_with_status(
+                    env,
+                    all_tasks,
+                    include_git_status=False,
+                )
+
+                if search:
+                    search_lower = search.lower()
+                    dashboards = [
+                        d for d in dashboards 
+                        if search_lower in d.get('title', '').lower() 
+                        or search_lower in d.get('slug', '').lower()
+                    ]
+
+                total = len(dashboards)
+                total_pages = (total + page_size - 1) // page_size if total > 0 else 1
+                start_idx = (page - 1) * page_size
+                end_idx = start_idx + page_size
+                paginated_dashboards = dashboards[start_idx:end_idx]
             
             logger.info(f"[get_dashboards][Coherence:OK] Returning {len(paginated_dashboards)} dashboards (page {page}/{total_pages}, total: {total})")
             
@@ -219,10 +447,23 @@ async def get_dashboards(
 async def get_database_mappings(
     source_env_id: str,
     target_env_id: str,
+    config_manager=Depends(get_config_manager),
     mapping_service=Depends(get_mapping_service),
     _ = Depends(has_permission("plugin:migration", "READ"))
 ):
     with belief_scope("get_database_mappings", f"source={source_env_id}, target={target_env_id}"):
+        # Validate environments exist
+        environments = config_manager.get_environments()
+        source_env = next((e for e in environments if e.id == source_env_id), None)
+        target_env = next((e for e in environments if e.id == target_env_id), None)
+        
+        if not source_env:
+            logger.error(f"[get_database_mappings][Coherence:Failed] Source environment not found: {source_env_id}")
+            raise HTTPException(status_code=404, detail="Source environment not found")
+        if not target_env:
+            logger.error(f"[get_database_mappings][Coherence:Failed] Target environment not found: {target_env_id}")
+            raise HTTPException(status_code=404, detail="Target environment not found")
+
         try:
             # Get mapping suggestions using MappingService
             suggestions = await mapping_service.get_suggestions(source_env_id, target_env_id)
@@ -250,17 +491,17 @@ async def get_database_mappings(
 
 # [DEF:get_dashboard_detail:Function]
 # @PURPOSE: Fetch detailed dashboard info with related charts and datasets
-# @PRE: env_id must be valid and dashboard_id must exist
+# @PRE: env_id must be valid and dashboard ref (slug or id) must exist
 # @POST: Returns dashboard detail payload for overview page
 # @RELATION: CALLS -> SupersetClient.get_dashboard_detail
-@router.get("/{dashboard_id:int}", response_model=DashboardDetailResponse)
+@router.get("/{dashboard_ref}", response_model=DashboardDetailResponse)
 async def get_dashboard_detail(
-    dashboard_id: int,
+    dashboard_ref: str,
     env_id: str,
     config_manager=Depends(get_config_manager),
     _ = Depends(has_permission("plugin:migration", "READ"))
 ):
-    with belief_scope("get_dashboard_detail", f"dashboard_id={dashboard_id}, env_id={env_id}"):
+    with belief_scope("get_dashboard_detail", f"dashboard_ref={dashboard_ref}, env_id={env_id}"):
         environments = config_manager.get_environments()
         env = next((e for e in environments if e.id == env_id), None)
         if not env:
@@ -269,9 +510,10 @@ async def get_dashboard_detail(
 
         try:
             client = SupersetClient(env)
+            dashboard_id = _resolve_dashboard_id_from_ref(dashboard_ref, client)
             detail = client.get_dashboard_detail(dashboard_id)
             logger.info(
-                f"[get_dashboard_detail][Coherence:OK] Dashboard {dashboard_id}: {detail.get('chart_count', 0)} charts, {detail.get('dataset_count', 0)} datasets"
+                f"[get_dashboard_detail][Coherence:OK] Dashboard ref={dashboard_ref} resolved_id={dashboard_id}: {detail.get('chart_count', 0)} charts, {detail.get('dataset_count', 0)} datasets"
             )
             return DashboardDetailResponse(**detail)
         except HTTPException:
@@ -317,17 +559,38 @@ def _task_matches_dashboard(task: Any, dashboard_id: int, env_id: Optional[str])
 
 # [DEF:get_dashboard_tasks_history:Function]
 # @PURPOSE: Returns history of backup and LLM validation tasks for a dashboard.
-# @PRE: dashboard_id is valid integer.
+# @PRE: dashboard ref (slug or id) is valid.
 # @POST: Response contains sorted task history (newest first).
-@router.get("/{dashboard_id:int}/tasks", response_model=DashboardTaskHistoryResponse)
+@router.get("/{dashboard_ref}/tasks", response_model=DashboardTaskHistoryResponse)
 async def get_dashboard_tasks_history(
-    dashboard_id: int,
+    dashboard_ref: str,
     env_id: Optional[str] = None,
     limit: int = Query(20, ge=1, le=100),
+    config_manager=Depends(get_config_manager),
     task_manager=Depends(get_task_manager),
     _ = Depends(has_permission("tasks", "READ"))
 ):
-    with belief_scope("get_dashboard_tasks_history", f"dashboard_id={dashboard_id}, env_id={env_id}, limit={limit}"):
+    with belief_scope("get_dashboard_tasks_history", f"dashboard_ref={dashboard_ref}, env_id={env_id}, limit={limit}"):
+        dashboard_id: Optional[int] = None
+        if dashboard_ref.isdigit():
+            dashboard_id = int(dashboard_ref)
+        elif env_id:
+            environments = config_manager.get_environments()
+            env = next((e for e in environments if e.id == env_id), None)
+            if not env:
+                logger.error(f"[get_dashboard_tasks_history][Coherence:Failed] Environment not found: {env_id}")
+                raise HTTPException(status_code=404, detail="Environment not found")
+            client = SupersetClient(env)
+            dashboard_id = _resolve_dashboard_id_from_ref(dashboard_ref, client)
+        else:
+            logger.error(
+                "[get_dashboard_tasks_history][Coherence:Failed] Non-numeric dashboard ref requires env_id"
+            )
+            raise HTTPException(
+                status_code=400,
+                detail="env_id is required when dashboard reference is a slug",
+            )
+
         matching_tasks = []
         for task in task_manager.get_all_tasks():
             if _task_matches_dashboard(task, dashboard_id, env_id):
@@ -370,7 +633,7 @@ async def get_dashboard_tasks_history(
                 )
             )
 
-        logger.info(f"[get_dashboard_tasks_history][Coherence:OK] Found {len(items)} tasks for dashboard {dashboard_id}")
+        logger.info(f"[get_dashboard_tasks_history][Coherence:OK] Found {len(items)} tasks for dashboard_ref={dashboard_ref}, dashboard_id={dashboard_id}")
         return DashboardTaskHistoryResponse(dashboard_id=dashboard_id, items=items)
 # [/DEF:get_dashboard_tasks_history:Function]
 
@@ -379,15 +642,15 @@ async def get_dashboard_tasks_history(
 # @PURPOSE: Proxies Superset dashboard thumbnail with cache support.
 # @PRE: env_id must exist.
 # @POST: Returns image bytes or 202 when thumbnail is being prepared by Superset.
-@router.get("/{dashboard_id:int}/thumbnail")
+@router.get("/{dashboard_ref}/thumbnail")
 async def get_dashboard_thumbnail(
-    dashboard_id: int,
+    dashboard_ref: str,
     env_id: str,
     force: bool = Query(False),
     config_manager=Depends(get_config_manager),
     _ = Depends(has_permission("plugin:migration", "READ"))
 ):
-    with belief_scope("get_dashboard_thumbnail", f"dashboard_id={dashboard_id}, env_id={env_id}, force={force}"):
+    with belief_scope("get_dashboard_thumbnail", f"dashboard_ref={dashboard_ref}, env_id={env_id}, force={force}"):
         environments = config_manager.get_environments()
         env = next((e for e in environments if e.id == env_id), None)
         if not env:
@@ -396,6 +659,7 @@ async def get_dashboard_thumbnail(
 
         try:
             client = SupersetClient(env)
+            dashboard_id = _resolve_dashboard_id_from_ref(dashboard_ref, client)
             digest = None
             thumb_endpoint = None
 

backend/src/api/routes/environments.py

@@ -20,6 +20,18 @@ from ...core.logger import belief_scope
 
 router = APIRouter(prefix="/api/environments", tags=["Environments"])
 
+
+# [DEF:_normalize_superset_env_url:Function]
+# @PURPOSE: Canonicalize Superset environment URL to base host/path without trailing /api/v1.
+# @PRE: raw_url can be empty.
+# @POST: Returns normalized base URL.
+def _normalize_superset_env_url(raw_url: str) -> str:
+    normalized = str(raw_url or "").strip().rstrip("/")
+    if normalized.lower().endswith("/api/v1"):
+        normalized = normalized[:-len("/api/v1")]
+    return normalized.rstrip("/")
+# [/DEF:_normalize_superset_env_url:Function]
+
 # [DEF:ScheduleSchema:DataClass]
 class ScheduleSchema(BaseModel):
     enabled: bool = False
@@ -31,6 +43,7 @@ class EnvironmentResponse(BaseModel):
     id: str
     name: str
     url: str
+    stage: str = "DEV"
     is_production: bool = False
     backup_schedule: Optional[ScheduleSchema] = None
 # [/DEF:EnvironmentResponse:DataClass]
@@ -59,18 +72,26 @@ async def get_environments(
     # Ensure envs is a list
     if not isinstance(envs, list):
         envs = []
-    return [
-        EnvironmentResponse(
-            id=e.id,
-            name=e.name,
-            url=e.url,
-            is_production=getattr(e, "is_production", False),
-            backup_schedule=ScheduleSchema(
-                enabled=e.backup_schedule.enabled,
-                cron_expression=e.backup_schedule.cron_expression
-            ) if getattr(e, 'backup_schedule', None) else None
-        ) for e in envs
-    ]
+    response_items = []
+    for e in envs:
+        resolved_stage = str(
+            getattr(e, "stage", "")
+            or ("PROD" if bool(getattr(e, "is_production", False)) else "DEV")
+        ).upper()
+        response_items.append(
+            EnvironmentResponse(
+                id=e.id,
+                name=e.name,
+                url=_normalize_superset_env_url(e.url),
+                stage=resolved_stage,
+                is_production=(resolved_stage == "PROD"),
+                backup_schedule=ScheduleSchema(
+                    enabled=e.backup_schedule.enabled,
+                    cron_expression=e.backup_schedule.cron_expression
+                ) if getattr(e, 'backup_schedule', None) else None
+            )
+        )
+    return response_items
 # [/DEF:get_environments:Function]
 
 # [DEF:update_environment_schedule:Function]

backend/src/api/routes/git.py

@@ -14,16 +14,22 @@ from fastapi import APIRouter, Depends, HTTPException
 from sqlalchemy.orm import Session
 from typing import List, Optional
 import typing
+import os
 from src.dependencies import get_config_manager, has_permission
 from src.core.database import get_db
-from src.models.git import GitServerConfig, GitRepository
+from src.models.git import GitServerConfig, GitRepository, GitProvider
 from src.api.routes.git_schemas import (
     GitServerConfigSchema, GitServerConfigCreate,
     BranchSchema, BranchCreate,
     BranchCheckout, CommitSchema, CommitCreate,
-    DeploymentEnvironmentSchema, DeployRequest, RepoInitRequest
+    DeploymentEnvironmentSchema, DeployRequest, RepoInitRequest,
+    RepoStatusBatchRequest, RepoStatusBatchResponse,
+    GiteaRepoCreateRequest, GiteaRepoSchema,
+    RemoteRepoCreateRequest, RemoteRepoSchema,
+    PromoteRequest, PromoteResponse,
 )
 from src.services.git_service import GitService
+from src.core.superset_client import SupersetClient
 from src.core.logger import logger, belief_scope
 from ...services.llm_prompt_templates import (
     DEFAULT_LLM_PROMPTS,
@@ -33,6 +39,173 @@ from ...services.llm_prompt_templates import (
 
 router = APIRouter(tags=["git"])
 git_service = GitService()
+MAX_REPOSITORY_STATUS_BATCH = 50
+
+
+# [DEF:_build_no_repo_status_payload:Function]
+# @PURPOSE: Build a consistent status payload for dashboards without initialized repositories.
+# @PRE: None.
+# @POST: Returns a stable payload compatible with frontend repository status parsing.
+# @RETURN: dict
+def _build_no_repo_status_payload() -> dict:
+    return {
+        "is_dirty": False,
+        "untracked_files": [],
+        "modified_files": [],
+        "staged_files": [],
+        "current_branch": None,
+        "upstream_branch": None,
+        "has_upstream": False,
+        "ahead_count": 0,
+        "behind_count": 0,
+        "is_diverged": False,
+        "sync_state": "NO_REPO",
+        "sync_status": "NO_REPO",
+        "has_repo": False,
+    }
+# [/DEF:_build_no_repo_status_payload:Function]
+
+
+# [DEF:_handle_unexpected_git_route_error:Function]
+# @PURPOSE: Convert unexpected route-level exceptions to stable 500 API responses.
+# @PRE: `error` is a non-HTTPException instance.
+# @POST: Raises HTTPException(500) with route-specific context.
+# @PARAM: route_name (str)
+# @PARAM: error (Exception)
+def _handle_unexpected_git_route_error(route_name: str, error: Exception) -> None:
+    logger.error(f"[{route_name}][Coherence:Failed] {error}")
+    raise HTTPException(status_code=500, detail=f"{route_name} failed: {str(error)}")
+# [/DEF:_handle_unexpected_git_route_error:Function]
+
+
+# [DEF:_resolve_repository_status:Function]
+# @PURPOSE: Resolve repository status for one dashboard with graceful NO_REPO semantics.
+# @PRE: `dashboard_id` is a valid integer.
+# @POST: Returns standard status payload or `NO_REPO` payload when repository path is absent.
+# @PARAM: dashboard_id (int)
+# @RETURN: dict
+def _resolve_repository_status(dashboard_id: int) -> dict:
+    repo_path = git_service._get_repo_path(dashboard_id)
+    if not os.path.exists(repo_path):
+        logger.debug(
+            f"[get_repository_status][Action] Repository is not initialized for dashboard {dashboard_id}"
+        )
+        return _build_no_repo_status_payload()
+
+    try:
+        return git_service.get_status(dashboard_id)
+    except HTTPException as e:
+        if e.status_code == 404:
+            logger.debug(
+                f"[get_repository_status][Action] Repository is not initialized for dashboard {dashboard_id}"
+            )
+            return _build_no_repo_status_payload()
+        raise
+# [/DEF:_resolve_repository_status:Function]
+
+
+# [DEF:_get_git_config_or_404:Function]
+# @PURPOSE: Resolve GitServerConfig by id or raise 404.
+# @PRE: db session is available.
+# @POST: Returns GitServerConfig model.
+def _get_git_config_or_404(db: Session, config_id: str) -> GitServerConfig:
+    config = db.query(GitServerConfig).filter(GitServerConfig.id == config_id).first()
+    if not config:
+        raise HTTPException(status_code=404, detail="Git configuration not found")
+    return config
+# [/DEF:_get_git_config_or_404:Function]
+
+
+# [DEF:_find_dashboard_id_by_slug:Function]
+# @PURPOSE: Resolve dashboard numeric ID by slug in a specific environment.
+# @PRE: dashboard_slug is non-empty.
+# @POST: Returns dashboard ID or None when not found.
+def _find_dashboard_id_by_slug(
+    client: SupersetClient,
+    dashboard_slug: str,
+) -> Optional[int]:
+    query_variants = [
+        {"filters": [{"col": "slug", "opr": "eq", "value": dashboard_slug}], "page": 0, "page_size": 1},
+        {"filters": [{"col": "slug", "op": "eq", "value": dashboard_slug}], "page": 0, "page_size": 1},
+    ]
+
+    for query in query_variants:
+        try:
+            _count, dashboards = client.get_dashboards_page(query=query)
+            if dashboards:
+                resolved_id = dashboards[0].get("id")
+                if resolved_id is not None:
+                    return int(resolved_id)
+        except Exception:
+            continue
+    return None
+# [/DEF:_find_dashboard_id_by_slug:Function]
+
+
+# [DEF:_resolve_dashboard_id_from_ref:Function]
+# @PURPOSE: Resolve dashboard ID from slug-or-id reference for Git routes.
+# @PRE: dashboard_ref is provided; env_id is required for slug values.
+# @POST: Returns numeric dashboard ID or raises HTTPException.
+def _resolve_dashboard_id_from_ref(
+    dashboard_ref: str,
+    config_manager,
+    env_id: Optional[str] = None,
+) -> int:
+    normalized_ref = str(dashboard_ref or "").strip()
+    if not normalized_ref:
+        raise HTTPException(status_code=400, detail="dashboard_ref is required")
+
+    if normalized_ref.isdigit():
+        return int(normalized_ref)
+
+    if not env_id:
+        raise HTTPException(
+            status_code=400,
+            detail="env_id is required for slug-based Git operations",
+        )
+
+    environments = config_manager.get_environments()
+    env = next((e for e in environments if e.id == env_id), None)
+    if not env:
+        raise HTTPException(status_code=404, detail="Environment not found")
+
+    dashboard_id = _find_dashboard_id_by_slug(SupersetClient(env), normalized_ref)
+    if dashboard_id is None:
+        raise HTTPException(status_code=404, detail=f"Dashboard slug '{normalized_ref}' not found")
+    return dashboard_id
+# [/DEF:_resolve_dashboard_id_from_ref:Function]
+
+
+# [DEF:_resolve_repo_key_from_ref:Function]
+# @PURPOSE: Resolve repository folder key with slug-first strategy and deterministic fallback.
+# @PRE: dashboard_id is resolved and valid.
+# @POST: Returns safe key to be used in local repository path.
+# @RETURN: str
+def _resolve_repo_key_from_ref(
+    dashboard_ref: str,
+    dashboard_id: int,
+    config_manager,
+    env_id: Optional[str] = None,
+) -> str:
+    normalized_ref = str(dashboard_ref or "").strip()
+    if normalized_ref and not normalized_ref.isdigit():
+        return normalized_ref
+
+    if env_id:
+        try:
+            environments = config_manager.get_environments()
+            env = next((e for e in environments if e.id == env_id), None)
+            if env:
+                payload = SupersetClient(env).get_dashboard(dashboard_id)
+                dashboard_data = payload.get("result", payload) if isinstance(payload, dict) else {}
+                dashboard_slug = dashboard_data.get("slug")
+                if dashboard_slug:
+                    return str(dashboard_slug)
+        except Exception:
+            pass
+
+    return f"dashboard-{dashboard_id}"
+# [/DEF:_resolve_repo_key_from_ref:Function]
 
 # [DEF:get_git_configs:Function]
 # @PURPOSE: List all configured Git servers.
@@ -107,20 +280,176 @@ async def test_git_config(
             raise HTTPException(status_code=400, detail="Connection failed")
 # [/DEF:test_git_config:Function]
 
+
+# [DEF:list_gitea_repositories:Function]
+# @PURPOSE: List repositories in Gitea for a saved Gitea config.
+# @PRE: config_id exists and provider is GITEA.
+# @POST: Returns repositories visible to PAT user.
+@router.get("/config/{config_id}/gitea/repos", response_model=List[GiteaRepoSchema])
+async def list_gitea_repositories(
+    config_id: str,
+    db: Session = Depends(get_db),
+    _ = Depends(has_permission("admin:settings", "READ"))
+):
+    with belief_scope("list_gitea_repositories"):
+        config = _get_git_config_or_404(db, config_id)
+        if config.provider != GitProvider.GITEA:
+            raise HTTPException(status_code=400, detail="This endpoint supports GITEA provider only")
+        repos = await git_service.list_gitea_repositories(config.url, config.pat)
+        return [
+            GiteaRepoSchema(
+                name=repo.get("name", ""),
+                full_name=repo.get("full_name", ""),
+                private=bool(repo.get("private", False)),
+                clone_url=repo.get("clone_url"),
+                html_url=repo.get("html_url"),
+                ssh_url=repo.get("ssh_url"),
+                default_branch=repo.get("default_branch"),
+            )
+            for repo in repos
+        ]
+# [/DEF:list_gitea_repositories:Function]
+
+
+# [DEF:create_gitea_repository:Function]
+# @PURPOSE: Create a repository in Gitea for a saved Gitea config.
+# @PRE: config_id exists and provider is GITEA.
+# @POST: Returns created repository payload.
+@router.post("/config/{config_id}/gitea/repos", response_model=GiteaRepoSchema)
+async def create_gitea_repository(
+    config_id: str,
+    request: GiteaRepoCreateRequest,
+    db: Session = Depends(get_db),
+    _ = Depends(has_permission("admin:settings", "WRITE"))
+):
+    with belief_scope("create_gitea_repository"):
+        config = _get_git_config_or_404(db, config_id)
+        if config.provider != GitProvider.GITEA:
+            raise HTTPException(status_code=400, detail="This endpoint supports GITEA provider only")
+        repo = await git_service.create_gitea_repository(
+            server_url=config.url,
+            pat=config.pat,
+            name=request.name,
+            private=request.private,
+            description=request.description,
+            auto_init=request.auto_init,
+            default_branch=request.default_branch,
+        )
+        return GiteaRepoSchema(
+            name=repo.get("name", ""),
+            full_name=repo.get("full_name", ""),
+            private=bool(repo.get("private", False)),
+            clone_url=repo.get("clone_url"),
+            html_url=repo.get("html_url"),
+            ssh_url=repo.get("ssh_url"),
+            default_branch=repo.get("default_branch"),
+        )
+# [/DEF:create_gitea_repository:Function]
+
+
+# [DEF:create_remote_repository:Function]
+# @PURPOSE: Create repository on remote Git server using selected provider config.
+# @PRE: config_id exists and PAT has creation permissions.
+# @POST: Returns normalized remote repository payload.
+@router.post("/config/{config_id}/repositories", response_model=RemoteRepoSchema)
+async def create_remote_repository(
+    config_id: str,
+    request: RemoteRepoCreateRequest,
+    db: Session = Depends(get_db),
+    _ = Depends(has_permission("admin:settings", "WRITE"))
+):
+    with belief_scope("create_remote_repository"):
+        config = _get_git_config_or_404(db, config_id)
+
+        if config.provider == GitProvider.GITEA:
+            repo = await git_service.create_gitea_repository(
+                server_url=config.url,
+                pat=config.pat,
+                name=request.name,
+                private=request.private,
+                description=request.description,
+                auto_init=request.auto_init,
+                default_branch=request.default_branch,
+            )
+        elif config.provider == GitProvider.GITHUB:
+            repo = await git_service.create_github_repository(
+                server_url=config.url,
+                pat=config.pat,
+                name=request.name,
+                private=request.private,
+                description=request.description,
+                auto_init=request.auto_init,
+                default_branch=request.default_branch,
+            )
+        elif config.provider == GitProvider.GITLAB:
+            repo = await git_service.create_gitlab_repository(
+                server_url=config.url,
+                pat=config.pat,
+                name=request.name,
+                private=request.private,
+                description=request.description,
+                auto_init=request.auto_init,
+                default_branch=request.default_branch,
+            )
+        else:
+            raise HTTPException(status_code=501, detail=f"Provider {config.provider} is not supported")
+
+        return RemoteRepoSchema(
+            provider=config.provider,
+            name=repo.get("name", ""),
+            full_name=repo.get("full_name", repo.get("name", "")),
+            private=bool(repo.get("private", False)),
+            clone_url=repo.get("clone_url"),
+            html_url=repo.get("html_url"),
+            ssh_url=repo.get("ssh_url"),
+            default_branch=repo.get("default_branch"),
+        )
+# [/DEF:create_remote_repository:Function]
+
+
+# [DEF:delete_gitea_repository:Function]
+# @PURPOSE: Delete repository in Gitea for a saved Gitea config.
+# @PRE: config_id exists and provider is GITEA.
+# @POST: Target repository is deleted on Gitea.
+@router.delete("/config/{config_id}/gitea/repos/{owner}/{repo_name}")
+async def delete_gitea_repository(
+    config_id: str,
+    owner: str,
+    repo_name: str,
+    db: Session = Depends(get_db),
+    _ = Depends(has_permission("admin:settings", "WRITE"))
+):
+    with belief_scope("delete_gitea_repository"):
+        config = _get_git_config_or_404(db, config_id)
+        if config.provider != GitProvider.GITEA:
+            raise HTTPException(status_code=400, detail="This endpoint supports GITEA provider only")
+        await git_service.delete_gitea_repository(
+            server_url=config.url,
+            pat=config.pat,
+            owner=owner,
+            repo_name=repo_name,
+        )
+        return {"status": "success", "message": "Repository deleted"}
+# [/DEF:delete_gitea_repository:Function]
+
 # [DEF:init_repository:Function]
 # @PURPOSE: Link a dashboard to a Git repository and perform initial clone/init.
-# @PRE: `dashboard_id` exists and `init_data` contains valid config_id and remote_url.
+# @PRE: `dashboard_ref` exists and `init_data` contains valid config_id and remote_url.
 # @POST: Repository is initialized on disk and a GitRepository record is saved in DB.
-# @PARAM: dashboard_id (int)
+# @PARAM: dashboard_ref (str)
 # @PARAM: init_data (RepoInitRequest)
-@router.post("/repositories/{dashboard_id}/init")
+@router.post("/repositories/{dashboard_ref}/init")
 async def init_repository(
-    dashboard_id: int,
+    dashboard_ref: str,
     init_data: RepoInitRequest,
+    env_id: Optional[str] = None,
+    config_manager=Depends(get_config_manager),
     db: Session = Depends(get_db),
     _ = Depends(has_permission("plugin:git", "EXECUTE"))
 ):
     with belief_scope("init_repository"):
+        dashboard_id = _resolve_dashboard_id_from_ref(dashboard_ref, config_manager, env_id)
+        repo_key = _resolve_repo_key_from_ref(dashboard_ref, dashboard_id, config_manager, env_id)
         # 1. Get config
         config = db.query(GitServerConfig).filter(GitServerConfig.id == init_data.config_id).first()
         if not config:
@@ -129,10 +458,10 @@ async def init_repository(
         try:
             # 2. Perform Git clone/init
             logger.info(f"[init_repository][Action] Initializing repo for dashboard {dashboard_id}")
-            git_service.init_repo(dashboard_id, init_data.remote_url, config.pat)
+            git_service.init_repo(dashboard_id, init_data.remote_url, config.pat, repo_key=repo_key)
             
             # 3. Save to DB
-            repo_path = git_service._get_repo_path(dashboard_id)
+            repo_path = git_service._get_repo_path(dashboard_id, repo_key=repo_key)
             db_repo = db.query(GitRepository).filter(GitRepository.dashboard_id == dashboard_id).first()
             if not db_repo:
                 db_repo = GitRepository(
@@ -153,137 +482,172 @@ async def init_repository(
         except Exception as e:
             db.rollback()
             logger.error(f"[init_repository][Coherence:Failed] Failed to init repository: {e}")
-            raise HTTPException(status_code=400, detail=str(e))
+            if isinstance(e, HTTPException):
+                raise
+            _handle_unexpected_git_route_error("init_repository", e)
 # [/DEF:init_repository:Function]
 
 # [DEF:get_branches:Function]
 # @PURPOSE: List all branches for a dashboard's repository.
-# @PRE: Repository for `dashboard_id` is initialized.
+# @PRE: Repository for `dashboard_ref` is initialized.
 # @POST: Returns a list of branches from the local repository.
-# @PARAM: dashboard_id (int)
+# @PARAM: dashboard_ref (str)
 # @RETURN: List[BranchSchema]
-@router.get("/repositories/{dashboard_id}/branches", response_model=List[BranchSchema])
+@router.get("/repositories/{dashboard_ref}/branches", response_model=List[BranchSchema])
 async def get_branches(
-    dashboard_id: int,
+    dashboard_ref: str,
+    env_id: Optional[str] = None,
+    config_manager=Depends(get_config_manager),
     _ = Depends(has_permission("plugin:git", "EXECUTE"))
 ):
     with belief_scope("get_branches"):
         try:
+            dashboard_id = _resolve_dashboard_id_from_ref(dashboard_ref, config_manager, env_id)
             return git_service.list_branches(dashboard_id)
+        except HTTPException:
+            raise
         except Exception as e:
-            raise HTTPException(status_code=404, detail=str(e))
+            _handle_unexpected_git_route_error("get_branches", e)
 # [/DEF:get_branches:Function]
 
 # [DEF:create_branch:Function]
 # @PURPOSE: Create a new branch in the dashboard's repository.
-# @PRE: `dashboard_id` repository exists and `branch_data` has name and from_branch.
+# @PRE: `dashboard_ref` repository exists and `branch_data` has name and from_branch.
 # @POST: A new branch is created in the local repository.
-# @PARAM: dashboard_id (int)
+# @PARAM: dashboard_ref (str)
 # @PARAM: branch_data (BranchCreate)
-@router.post("/repositories/{dashboard_id}/branches")
+@router.post("/repositories/{dashboard_ref}/branches")
 async def create_branch(
-    dashboard_id: int,
+    dashboard_ref: str,
     branch_data: BranchCreate,
+    env_id: Optional[str] = None,
+    config_manager=Depends(get_config_manager),
     _ = Depends(has_permission("plugin:git", "EXECUTE"))
 ):
     with belief_scope("create_branch"):
         try:
+            dashboard_id = _resolve_dashboard_id_from_ref(dashboard_ref, config_manager, env_id)
             git_service.create_branch(dashboard_id, branch_data.name, branch_data.from_branch)
             return {"status": "success"}
+        except HTTPException:
+            raise
         except Exception as e:
-            raise HTTPException(status_code=400, detail=str(e))
+            _handle_unexpected_git_route_error("create_branch", e)
 # [/DEF:create_branch:Function]
 
 # [DEF:checkout_branch:Function]
 # @PURPOSE: Switch the dashboard's repository to a specific branch.
-# @PRE: `dashboard_id` repository exists and branch `checkout_data.name` exists.
+# @PRE: `dashboard_ref` repository exists and branch `checkout_data.name` exists.
 # @POST: The local repository HEAD is moved to the specified branch.
-# @PARAM: dashboard_id (int)
+# @PARAM: dashboard_ref (str)
 # @PARAM: checkout_data (BranchCheckout)
-@router.post("/repositories/{dashboard_id}/checkout")
+@router.post("/repositories/{dashboard_ref}/checkout")
 async def checkout_branch(
-    dashboard_id: int,
+    dashboard_ref: str,
     checkout_data: BranchCheckout,
+    env_id: Optional[str] = None,
+    config_manager=Depends(get_config_manager),
     _ = Depends(has_permission("plugin:git", "EXECUTE"))
 ):
     with belief_scope("checkout_branch"):
         try:
+            dashboard_id = _resolve_dashboard_id_from_ref(dashboard_ref, config_manager, env_id)
             git_service.checkout_branch(dashboard_id, checkout_data.name)
             return {"status": "success"}
+        except HTTPException:
+            raise
         except Exception as e:
-            raise HTTPException(status_code=400, detail=str(e))
+            _handle_unexpected_git_route_error("checkout_branch", e)
 # [/DEF:checkout_branch:Function]
 
 # [DEF:commit_changes:Function]
 # @PURPOSE: Stage and commit changes in the dashboard's repository.
-# @PRE: `dashboard_id` repository exists and `commit_data` has message and files.
+# @PRE: `dashboard_ref` repository exists and `commit_data` has message and files.
 # @POST: Specified files are staged and a new commit is created.
-# @PARAM: dashboard_id (int)
+# @PARAM: dashboard_ref (str)
 # @PARAM: commit_data (CommitCreate)
-@router.post("/repositories/{dashboard_id}/commit")
+@router.post("/repositories/{dashboard_ref}/commit")
 async def commit_changes(
-    dashboard_id: int,
+    dashboard_ref: str,
     commit_data: CommitCreate,
+    env_id: Optional[str] = None,
+    config_manager=Depends(get_config_manager),
     _ = Depends(has_permission("plugin:git", "EXECUTE"))
 ):
     with belief_scope("commit_changes"):
         try:
+            dashboard_id = _resolve_dashboard_id_from_ref(dashboard_ref, config_manager, env_id)
             git_service.commit_changes(dashboard_id, commit_data.message, commit_data.files)
             return {"status": "success"}
+        except HTTPException:
+            raise
         except Exception as e:
-            raise HTTPException(status_code=400, detail=str(e))
+            _handle_unexpected_git_route_error("commit_changes", e)
 # [/DEF:commit_changes:Function]
 
 # [DEF:push_changes:Function]
 # @PURPOSE: Push local commits to the remote repository.
-# @PRE: `dashboard_id` repository exists and has a remote configured.
+# @PRE: `dashboard_ref` repository exists and has a remote configured.
 # @POST: Local commits are pushed to the remote repository.
-# @PARAM: dashboard_id (int)
-@router.post("/repositories/{dashboard_id}/push")
+# @PARAM: dashboard_ref (str)
+@router.post("/repositories/{dashboard_ref}/push")
 async def push_changes(
-    dashboard_id: int,
+    dashboard_ref: str,
+    env_id: Optional[str] = None,
+    config_manager=Depends(get_config_manager),
     _ = Depends(has_permission("plugin:git", "EXECUTE"))
 ):
     with belief_scope("push_changes"):
         try:
+            dashboard_id = _resolve_dashboard_id_from_ref(dashboard_ref, config_manager, env_id)
             git_service.push_changes(dashboard_id)
             return {"status": "success"}
+        except HTTPException:
+            raise
         except Exception as e:
-            raise HTTPException(status_code=400, detail=str(e))
+            _handle_unexpected_git_route_error("push_changes", e)
 # [/DEF:push_changes:Function]
 
 # [DEF:pull_changes:Function]
 # @PURPOSE: Pull changes from the remote repository.
-# @PRE: `dashboard_id` repository exists and has a remote configured.
+# @PRE: `dashboard_ref` repository exists and has a remote configured.
 # @POST: Remote changes are fetched and merged into the local branch.
-# @PARAM: dashboard_id (int)
-@router.post("/repositories/{dashboard_id}/pull")
+# @PARAM: dashboard_ref (str)
+@router.post("/repositories/{dashboard_ref}/pull")
 async def pull_changes(
-    dashboard_id: int,
+    dashboard_ref: str,
+    env_id: Optional[str] = None,
+    config_manager=Depends(get_config_manager),
     _ = Depends(has_permission("plugin:git", "EXECUTE"))
 ):
     with belief_scope("pull_changes"):
         try:
+            dashboard_id = _resolve_dashboard_id_from_ref(dashboard_ref, config_manager, env_id)
             git_service.pull_changes(dashboard_id)
             return {"status": "success"}
+        except HTTPException:
+            raise
         except Exception as e:
-            raise HTTPException(status_code=400, detail=str(e))
+            _handle_unexpected_git_route_error("pull_changes", e)
 # [/DEF:pull_changes:Function]
 
 # [DEF:sync_dashboard:Function]
 # @PURPOSE: Sync dashboard state from Superset to Git using the GitPlugin.
-# @PRE: `dashboard_id` is valid; GitPlugin is available.
+# @PRE: `dashboard_ref` is valid; GitPlugin is available.
 # @POST: Dashboard YAMLs are exported from Superset and committed to Git.
-# @PARAM: dashboard_id (int)
+# @PARAM: dashboard_ref (str)
 # @PARAM: source_env_id (Optional[str])
-@router.post("/repositories/{dashboard_id}/sync")
+@router.post("/repositories/{dashboard_ref}/sync")
 async def sync_dashboard(
-    dashboard_id: int,
+    dashboard_ref: str,
+    env_id: Optional[str] = None,
     source_env_id: typing.Optional[str] = None,
+    config_manager=Depends(get_config_manager),
     _ = Depends(has_permission("plugin:git", "EXECUTE"))
 ):
     with belief_scope("sync_dashboard"):
         try:
+            dashboard_id = _resolve_dashboard_id_from_ref(dashboard_ref, config_manager, env_id)
             from src.plugins.git_plugin import GitPlugin
             plugin = GitPlugin()
             return await plugin.execute({
@@ -291,10 +655,113 @@ async def sync_dashboard(
                 "dashboard_id": dashboard_id,
                 "source_env_id": source_env_id
             })
+        except HTTPException:
+            raise
         except Exception as e:
-            raise HTTPException(status_code=400, detail=str(e))
+            _handle_unexpected_git_route_error("sync_dashboard", e)
 # [/DEF:sync_dashboard:Function]
 
+
+# [DEF:promote_dashboard:Function]
+# @PURPOSE: Promote changes between branches via MR or direct merge.
+# @PRE: dashboard repository is initialized and Git config is valid.
+# @POST: Returns promotion result metadata.
+@router.post("/repositories/{dashboard_ref}/promote", response_model=PromoteResponse)
+async def promote_dashboard(
+    dashboard_ref: str,
+    payload: PromoteRequest,
+    env_id: Optional[str] = None,
+    config_manager=Depends(get_config_manager),
+    db: Session = Depends(get_db),
+    _ = Depends(has_permission("plugin:git", "EXECUTE"))
+):
+    with belief_scope("promote_dashboard"):
+        dashboard_id = _resolve_dashboard_id_from_ref(dashboard_ref, config_manager, env_id)
+        db_repo = db.query(GitRepository).filter(GitRepository.dashboard_id == dashboard_id).first()
+        if not db_repo:
+            raise HTTPException(status_code=404, detail=f"Repository for dashboard {dashboard_ref} is not initialized")
+        config = _get_git_config_or_404(db, db_repo.config_id)
+
+        from_branch = payload.from_branch.strip()
+        to_branch = payload.to_branch.strip()
+        if not from_branch or not to_branch:
+            raise HTTPException(status_code=400, detail="from_branch and to_branch are required")
+        if from_branch == to_branch:
+            raise HTTPException(status_code=400, detail="from_branch and to_branch must be different")
+
+        mode = (payload.mode or "mr").strip().lower()
+        if mode == "direct":
+            reason = (payload.reason or "").strip()
+            if not reason:
+                raise HTTPException(status_code=400, detail="Direct promote requires non-empty reason")
+            logger.warning(
+                "[promote_dashboard][PolicyViolation] Direct promote without MR by actor=unknown dashboard_ref=%s from=%s to=%s reason=%s",
+                dashboard_ref,
+                from_branch,
+                to_branch,
+                reason,
+            )
+            result = git_service.promote_direct_merge(
+                dashboard_id=dashboard_id,
+                from_branch=from_branch,
+                to_branch=to_branch,
+            )
+            return PromoteResponse(
+                mode="direct",
+                from_branch=from_branch,
+                to_branch=to_branch,
+                status=result.get("status", "merged"),
+                policy_violation=True,
+            )
+
+        title = (payload.title or "").strip() or f"Promote {from_branch} -> {to_branch}"
+        description = payload.description
+        if config.provider == GitProvider.GITEA:
+            pr = await git_service.create_gitea_pull_request(
+                server_url=config.url,
+                pat=config.pat,
+                remote_url=db_repo.remote_url,
+                from_branch=from_branch,
+                to_branch=to_branch,
+                title=title,
+                description=description,
+            )
+        elif config.provider == GitProvider.GITHUB:
+            pr = await git_service.create_github_pull_request(
+                server_url=config.url,
+                pat=config.pat,
+                remote_url=db_repo.remote_url,
+                from_branch=from_branch,
+                to_branch=to_branch,
+                title=title,
+                description=description,
+                draft=payload.draft,
+            )
+        elif config.provider == GitProvider.GITLAB:
+            pr = await git_service.create_gitlab_merge_request(
+                server_url=config.url,
+                pat=config.pat,
+                remote_url=db_repo.remote_url,
+                from_branch=from_branch,
+                to_branch=to_branch,
+                title=title,
+                description=description,
+                remove_source_branch=payload.remove_source_branch,
+            )
+        else:
+            raise HTTPException(status_code=501, detail=f"Provider {config.provider} does not support promotion API")
+
+        return PromoteResponse(
+            mode="mr",
+            from_branch=from_branch,
+            to_branch=to_branch,
+            status=pr.get("status", "opened"),
+            url=pr.get("url"),
+            reference_id=str(pr.get("id")) if pr.get("id") is not None else None,
+            policy_violation=False,
+        )
+# [/DEF:promote_dashboard:Function]
+
 # [DEF:get_environments:Function]
 # @PURPOSE: List all deployment environments.
 # @PRE: Config manager is accessible.
@@ -319,18 +786,21 @@ async def get_environments(
 
 # [DEF:deploy_dashboard:Function]
 # @PURPOSE: Deploy dashboard from Git to a target environment.
-# @PRE: `dashboard_id` and `deploy_data.environment_id` are valid.
+# @PRE: `dashboard_ref` and `deploy_data.environment_id` are valid.
 # @POST: Dashboard YAMLs are read from Git and imported into the target Superset.
-# @PARAM: dashboard_id (int)
+# @PARAM: dashboard_ref (str)
 # @PARAM: deploy_data (DeployRequest)
-@router.post("/repositories/{dashboard_id}/deploy")
+@router.post("/repositories/{dashboard_ref}/deploy")
 async def deploy_dashboard(
-    dashboard_id: int,
+    dashboard_ref: str,
     deploy_data: DeployRequest,
+    env_id: Optional[str] = None,
+    config_manager=Depends(get_config_manager),
     _ = Depends(has_permission("plugin:git", "EXECUTE"))
 ):
     with belief_scope("deploy_dashboard"):
         try:
+            dashboard_id = _resolve_dashboard_id_from_ref(dashboard_ref, config_manager, env_id)
             from src.plugins.git_plugin import GitPlugin
             plugin = GitPlugin()
             return await plugin.execute({
@@ -338,84 +808,147 @@ async def deploy_dashboard(
                 "dashboard_id": dashboard_id,
                 "environment_id": deploy_data.environment_id
             })
+        except HTTPException:
+            raise
         except Exception as e:
-            raise HTTPException(status_code=400, detail=str(e))
+            _handle_unexpected_git_route_error("deploy_dashboard", e)
 # [/DEF:deploy_dashboard:Function]
 
 # [DEF:get_history:Function]
 # @PURPOSE: View commit history for a dashboard's repository.
-# @PRE: `dashboard_id` repository exists.
+# @PRE: `dashboard_ref` repository exists.
 # @POST: Returns a list of recent commits from the repository.
-# @PARAM: dashboard_id (int)
+# @PARAM: dashboard_ref (str)
 # @PARAM: limit (int)
 # @RETURN: List[CommitSchema]
-@router.get("/repositories/{dashboard_id}/history", response_model=List[CommitSchema])
+@router.get("/repositories/{dashboard_ref}/history", response_model=List[CommitSchema])
 async def get_history(
-    dashboard_id: int,
+    dashboard_ref: str,
     limit: int = 50,
+    env_id: Optional[str] = None,
+    config_manager=Depends(get_config_manager),
     _ = Depends(has_permission("plugin:git", "EXECUTE"))
 ):
     with belief_scope("get_history"):
         try:
+            dashboard_id = _resolve_dashboard_id_from_ref(dashboard_ref, config_manager, env_id)
             return git_service.get_commit_history(dashboard_id, limit)
+        except HTTPException:
+            raise
         except Exception as e:
-            raise HTTPException(status_code=404, detail=str(e))
+            _handle_unexpected_git_route_error("get_history", e)
 # [/DEF:get_history:Function]
 
 # [DEF:get_repository_status:Function]
 # @PURPOSE: Get current Git status for a dashboard repository.
-# @PRE: `dashboard_id` repository exists.
-# @POST: Returns the status of the working directory (staged, unstaged, untracked).
-# @PARAM: dashboard_id (int)
+# @PRE: `dashboard_ref` resolves to a valid dashboard.
+# @POST: Returns repository status; if repo is not initialized, returns `NO_REPO` payload.
+# @PARAM: dashboard_ref (str)
 # @RETURN: dict
-@router.get("/repositories/{dashboard_id}/status")
+@router.get("/repositories/{dashboard_ref}/status")
 async def get_repository_status(
-    dashboard_id: int,
+    dashboard_ref: str,
+    env_id: Optional[str] = None,
+    config_manager=Depends(get_config_manager),
     _ = Depends(has_permission("plugin:git", "EXECUTE"))
 ):
     with belief_scope("get_repository_status"):
         try:
-            return git_service.get_status(dashboard_id)
+            dashboard_id = _resolve_dashboard_id_from_ref(dashboard_ref, config_manager, env_id)
+            return _resolve_repository_status(dashboard_id)
+        except HTTPException:
+            raise
         except Exception as e:
-            raise HTTPException(status_code=400, detail=str(e))
+            _handle_unexpected_git_route_error("get_repository_status", e)
 # [/DEF:get_repository_status:Function]
 
+
+# [DEF:get_repository_status_batch:Function]
+# @PURPOSE: Get Git statuses for multiple dashboard repositories in one request.
+# @PRE: `request.dashboard_ids` is provided.
+# @POST: Returns `statuses` map where each key is dashboard ID and value is repository status payload.
+# @PARAM: request (RepoStatusBatchRequest)
+# @RETURN: RepoStatusBatchResponse
+@router.post("/repositories/status/batch", response_model=RepoStatusBatchResponse)
+async def get_repository_status_batch(
+    request: RepoStatusBatchRequest,
+    _ = Depends(has_permission("plugin:git", "EXECUTE"))
+):
+    with belief_scope("get_repository_status_batch"):
+        dashboard_ids = list(dict.fromkeys(request.dashboard_ids))
+        if len(dashboard_ids) > MAX_REPOSITORY_STATUS_BATCH:
+            logger.warning(
+                "[get_repository_status_batch][Action] Batch size %s exceeds limit %s. Truncating request.",
+                len(dashboard_ids),
+                MAX_REPOSITORY_STATUS_BATCH,
+            )
+            dashboard_ids = dashboard_ids[:MAX_REPOSITORY_STATUS_BATCH]
+
+        statuses = {}
+        for dashboard_id in dashboard_ids:
+            try:
+                statuses[str(dashboard_id)] = _resolve_repository_status(dashboard_id)
+            except HTTPException:
+                statuses[str(dashboard_id)] = {
+                    **_build_no_repo_status_payload(),
+                    "sync_state": "ERROR",
+                    "sync_status": "ERROR",
+                }
+            except Exception as e:
+                logger.error(
+                    f"[get_repository_status_batch][Coherence:Failed] Failed for dashboard {dashboard_id}: {e}"
+                )
+                statuses[str(dashboard_id)] = {
+                    **_build_no_repo_status_payload(),
+                    "sync_state": "ERROR",
+                    "sync_status": "ERROR",
+                }
+        return RepoStatusBatchResponse(statuses=statuses)
+# [/DEF:get_repository_status_batch:Function]
+
 # [DEF:get_repository_diff:Function]
 # @PURPOSE: Get Git diff for a dashboard repository.
-# @PRE: `dashboard_id` repository exists.
+# @PRE: `dashboard_ref` repository exists.
 # @POST: Returns the diff text for the specified file or all changes.
-# @PARAM: dashboard_id (int)
+# @PARAM: dashboard_ref (str)
 # @PARAM: file_path (Optional[str])
 # @PARAM: staged (bool)
 # @RETURN: str
-@router.get("/repositories/{dashboard_id}/diff")
+@router.get("/repositories/{dashboard_ref}/diff")
 async def get_repository_diff(
-    dashboard_id: int,
+    dashboard_ref: str,
     file_path: Optional[str] = None,
     staged: bool = False,
+    env_id: Optional[str] = None,
+    config_manager=Depends(get_config_manager),
     _ = Depends(has_permission("plugin:git", "EXECUTE"))
 ):
     with belief_scope("get_repository_diff"):
         try:
+            dashboard_id = _resolve_dashboard_id_from_ref(dashboard_ref, config_manager, env_id)
             diff_text = git_service.get_diff(dashboard_id, file_path, staged)
             return diff_text
+        except HTTPException:
+            raise
         except Exception as e:
-            raise HTTPException(status_code=400, detail=str(e))
+            _handle_unexpected_git_route_error("get_repository_diff", e)
 # [/DEF:get_repository_diff:Function]
 
 # [DEF:generate_commit_message:Function]
 # @PURPOSE: Generate a suggested commit message using LLM.
-# @PRE: Repository for `dashboard_id` is initialized.
+# @PRE: Repository for `dashboard_ref` is initialized.
 # @POST: Returns a suggested commit message string.
-@router.post("/repositories/{dashboard_id}/generate-message")
+@router.post("/repositories/{dashboard_ref}/generate-message")
 async def generate_commit_message(
-    dashboard_id: int,
-    db: Session = Depends(get_db),
+    dashboard_ref: str,
+    env_id: Optional[str] = None,
     config_manager = Depends(get_config_manager),
+    db: Session = Depends(get_db),
     _ = Depends(has_permission("plugin:git", "EXECUTE"))
 ):
     with belief_scope("generate_commit_message"):
         try:
+            dashboard_id = _resolve_dashboard_id_from_ref(dashboard_ref, config_manager, env_id)
             # 1. Get Diff
             diff = git_service.get_diff(dashboard_id, staged=True)
             if not diff:
@@ -466,9 +999,10 @@ async def generate_commit_message(
             )
             
             return {"message": message}
+        except HTTPException:
+            raise
         except Exception as e:
-            logger.error(f"Failed to generate commit message: {e}")
-            raise HTTPException(status_code=400, detail=str(e))
+            _handle_unexpected_git_route_error("generate_commit_message", e)
 # [/DEF:generate_commit_message:Function]
 
 # [/DEF:backend.src.api.routes.git:Module]

backend/src/api/routes/git_schemas.py

@@ -9,7 +9,7 @@
 # @INVARIANT: All schemas must be compatible with the FastAPI router.
 
 from pydantic import BaseModel, Field
-from typing import List, Optional
+from typing import Any, Dict, List, Optional
 from datetime import datetime
 from src.models.git import GitProvider, GitStatus, SyncStatus
 
@@ -141,4 +141,93 @@ class RepoInitRequest(BaseModel):
     remote_url: str
 # [/DEF:RepoInitRequest:Class]
 
-# [/DEF:backend.src.api.routes.git_schemas:Module]
+# [DEF:RepoStatusBatchRequest:Class]
+# @PURPOSE: Schema for requesting repository statuses for multiple dashboards in a single call.
+class RepoStatusBatchRequest(BaseModel):
+    dashboard_ids: List[int] = Field(default_factory=list, description="Dashboard IDs to resolve repository statuses for")
+# [/DEF:RepoStatusBatchRequest:Class]
+
+
+# [DEF:RepoStatusBatchResponse:Class]
+# @PURPOSE: Schema for returning repository statuses keyed by dashboard ID.
+class RepoStatusBatchResponse(BaseModel):
+    statuses: Dict[str, Dict[str, Any]]
+# [/DEF:RepoStatusBatchResponse:Class]
+
+
+# [DEF:GiteaRepoSchema:Class]
+# @PURPOSE: Schema describing a Gitea repository.
+class GiteaRepoSchema(BaseModel):
+    name: str
+    full_name: str
+    private: bool = False
+    clone_url: Optional[str] = None
+    html_url: Optional[str] = None
+    ssh_url: Optional[str] = None
+    default_branch: Optional[str] = None
+# [/DEF:GiteaRepoSchema:Class]
+
+
+# [DEF:GiteaRepoCreateRequest:Class]
+# @PURPOSE: Request schema for creating a Gitea repository.
+class GiteaRepoCreateRequest(BaseModel):
+    name: str = Field(..., min_length=1, max_length=255)
+    private: bool = True
+    description: Optional[str] = None
+    auto_init: bool = True
+    default_branch: Optional[str] = "main"
+# [/DEF:GiteaRepoCreateRequest:Class]
+
+
+# [DEF:RemoteRepoSchema:Class]
+# @PURPOSE: Provider-agnostic remote repository payload.
+class RemoteRepoSchema(BaseModel):
+    provider: GitProvider
+    name: str
+    full_name: str
+    private: bool = False
+    clone_url: Optional[str] = None
+    html_url: Optional[str] = None
+    ssh_url: Optional[str] = None
+    default_branch: Optional[str] = None
+# [/DEF:RemoteRepoSchema:Class]
+
+
+# [DEF:RemoteRepoCreateRequest:Class]
+# @PURPOSE: Provider-agnostic repository creation request.
+class RemoteRepoCreateRequest(BaseModel):
+    name: str = Field(..., min_length=1, max_length=255)
+    private: bool = True
+    description: Optional[str] = None
+    auto_init: bool = True
+    default_branch: Optional[str] = "main"
+# [/DEF:RemoteRepoCreateRequest:Class]
+
+
+# [DEF:PromoteRequest:Class]
+# @PURPOSE: Request schema for branch promotion workflow.
+class PromoteRequest(BaseModel):
+    from_branch: str = Field(..., min_length=1, max_length=255)
+    to_branch: str = Field(..., min_length=1, max_length=255)
+    mode: str = Field(default="mr", pattern="^(mr|direct)$")
+    title: Optional[str] = None
+    description: Optional[str] = None
+    reason: Optional[str] = None
+    draft: bool = False
+    remove_source_branch: bool = False
+# [/DEF:PromoteRequest:Class]
+
+
+# [DEF:PromoteResponse:Class]
+# @PURPOSE: Response schema for promotion operation result.
+class PromoteResponse(BaseModel):
+    mode: str
+    from_branch: str
+    to_branch: str
+    status: str
+    url: Optional[str] = None
+    reference_id: Optional[str] = None
+    policy_violation: bool = False
+# [/DEF:PromoteResponse:Class]
+
+# [/DEF:backend.src.api.routes.git_schemas:Module]

backend/src/api/routes/migration.py

@@ -14,6 +14,7 @@ from ...core.database import get_db
 from ...models.dashboard import DashboardMetadata, DashboardSelection
 from ...core.superset_client import SupersetClient
 from ...core.logger import belief_scope
+from ...core.migration.dry_run_orchestrator import MigrationDryRunService
 from ...core.mapping_service import IdMappingService
 from ...models.mapping import ResourceMapping
 
@@ -83,6 +84,44 @@ async def execute_migration(
         raise HTTPException(status_code=500, detail=f"Failed to create migration task: {str(e)}")
 # [/DEF:execute_migration:Function]
 
+
+# [DEF:dry_run_migration:Function]
+# @PURPOSE: Build pre-flight diff and risk summary without applying migration.
+# @PRE: Selection and environments are valid.
+# @POST: Returns deterministic JSON diff and risk scoring.
+@router.post("/migration/dry-run", response_model=Dict[str, Any])
+async def dry_run_migration(
+    selection: DashboardSelection,
+    config_manager=Depends(get_config_manager),
+    db: Session = Depends(get_db),
+    _ = Depends(has_permission("plugin:migration", "EXECUTE"))
+):
+    with belief_scope("dry_run_migration"):
+        environments = config_manager.get_environments()
+    env_map = {env.id: env for env in environments}
+    source_env = env_map.get(selection.source_env_id)
+    target_env = env_map.get(selection.target_env_id)
+    if not source_env or not target_env:
+        raise HTTPException(status_code=400, detail="Invalid source or target environment")
+    if selection.source_env_id == selection.target_env_id:
+        raise HTTPException(status_code=400, detail="Source and target environments must be different")
+    if not selection.selected_ids:
+        raise HTTPException(status_code=400, detail="No dashboards selected for dry run")
+
+    service = MigrationDryRunService()
+    source_client = SupersetClient(source_env)
+    target_client = SupersetClient(target_env)
+    try:
+        return service.run(
+            selection=selection,
+            source_client=source_client,
+            target_client=target_client,
+            db=db,
+        )
+    except ValueError as exc:
+        raise HTTPException(status_code=500, detail=str(exc)) from exc
+# [/DEF:dry_run_migration:Function]
+
 # [DEF:get_migration_settings:Function]
 # @PURPOSE: Get current migration Cron string explicitly.
 @router.get("/migration/settings", response_model=Dict[str, str])
@@ -221,4 +260,4 @@ async def trigger_sync_now(
         }
 # [/DEF:trigger_sync_now:Function]
 
-# [/DEF:backend.src.api.routes.migration:Module]
+# [/DEF:backend.src.api.routes.migration:Module]

backend/src/api/routes/reports.py

@@ -62,6 +62,20 @@ def _parse_csv_enum_list(raw: Optional[str], enum_cls, field_name: str) -> List:
 # @PRE: authenticated/authorized request and validated query params.
 # @POST: returns {items,total,page,page_size,has_next,applied_filters}.
 # @POST: deterministic error payload for invalid filters.
+#
+# @TEST_CONTRACT: ListReportsApi ->
+# {
+#   required_fields: {page: int, page_size: int, sort_by: str, sort_order: str},
+#   optional_fields: {task_types: str, statuses: str, search: str},
+#   invariants: [
+#       "Returns ReportCollection on success",
+#       "Raises HTTPException 400 for invalid query parameters"
+#   ]
+# }
+# @TEST_FIXTURE: valid_list_request -> {"page": 1, "page_size": 20}
+# @TEST_EDGE: invalid_task_type_filter -> raises HTTPException(400)
+# @TEST_EDGE: malformed_query -> raises HTTPException(400)
+# @TEST_INVARIANT: consistent_list_payload -> verifies: [valid_list_request]
 @router.get("", response_model=ReportCollection)
 async def list_reports(
     page: int = Query(1, ge=1),

backend/src/api/routes/settings.py

@@ -31,7 +31,38 @@ class LoggingConfigResponse(BaseModel):
     enable_belief_state: bool
 # [/DEF:LoggingConfigResponse:Class]
 
-router = APIRouter()
+router = APIRouter()
+
+
+# [DEF:_normalize_superset_env_url:Function]
+# @PURPOSE: Canonicalize Superset environment URL to base host/path without trailing /api/v1.
+# @PRE: raw_url can be empty.
+# @POST: Returns normalized base URL.
+def _normalize_superset_env_url(raw_url: str) -> str:
+    normalized = str(raw_url or "").strip().rstrip("/")
+    if normalized.lower().endswith("/api/v1"):
+        normalized = normalized[:-len("/api/v1")]
+    return normalized.rstrip("/")
+# [/DEF:_normalize_superset_env_url:Function]
+
+
+# [DEF:_validate_superset_connection_fast:Function]
+# @PURPOSE: Run lightweight Superset connectivity validation without full pagination scan.
+# @PRE: env contains valid URL and credentials.
+# @POST: Raises on auth/API failures; returns None on success.
+def _validate_superset_connection_fast(env: Environment) -> None:
+    client = SupersetClient(env)
+    # 1) Explicit auth check
+    client.authenticate()
+    # 2) Single lightweight API call to ensure read access
+    client.get_dashboards_page(
+        query={
+            "page": 0,
+            "page_size": 1,
+            "columns": ["id"],
+        }
+    )
+# [/DEF:_validate_superset_connection_fast:Function]
 
 # [DEF:get_settings:Function]
 # @PURPOSE: Retrieves all application settings.
@@ -112,14 +143,18 @@ async def update_storage_settings(
 # @PRE:     Config manager is available.
 # @POST:    Returns list of environments.
 # @RETURN: List[Environment] - List of environments.
-@router.get("/environments", response_model=List[Environment])
-async def get_environments(
+@router.get("/environments", response_model=List[Environment])
+async def get_environments(
     config_manager: ConfigManager = Depends(get_config_manager),
     _ = Depends(has_permission("admin:settings", "READ"))
-):
-    with belief_scope("get_environments"):
-        logger.info("[get_environments][Entry] Fetching environments")
-    return config_manager.get_environments()
+):
+    with belief_scope("get_environments"):
+        logger.info("[get_environments][Entry] Fetching environments")
+    environments = config_manager.get_environments()
+    return [
+        env.copy(update={"url": _normalize_superset_env_url(env.url)})
+        for env in environments
+    ]
 # [/DEF:get_environments:Function]
 
 # [DEF:add_environment:Function]
@@ -129,21 +164,21 @@ async def get_environments(
 # @PARAM: env (Environment) - The environment to add.
 # @RETURN: Environment - The added environment.
 @router.post("/environments", response_model=Environment)
-async def add_environment(
-    env: Environment,
+async def add_environment(
+    env: Environment,
     config_manager: ConfigManager = Depends(get_config_manager),
     _ = Depends(has_permission("admin:settings", "WRITE"))
-):
-    with belief_scope("add_environment"):
-        logger.info(f"[add_environment][Entry] Adding environment {env.id}")
+):
+    with belief_scope("add_environment"):
+        logger.info(f"[add_environment][Entry] Adding environment {env.id}")
+    env = env.copy(update={"url": _normalize_superset_env_url(env.url)})
     
-    # Validate connection before adding
-    try:
-        client = SupersetClient(env)
-        client.get_dashboards(query={"page_size": 1})
-    except Exception as e:
-        logger.error(f"[add_environment][Coherence:Failed] Connection validation failed: {e}")
-        raise HTTPException(status_code=400, detail=f"Connection validation failed: {e}")
+    # Validate connection before adding (fast path)
+    try:
+        _validate_superset_connection_fast(env)
+    except Exception as e:
+        logger.error(f"[add_environment][Coherence:Failed] Connection validation failed: {e}")
+        raise HTTPException(status_code=400, detail=f"Connection validation failed: {e}")
 
     config_manager.add_environment(env)
     return env
@@ -157,28 +192,29 @@ async def add_environment(
 # @PARAM: env (Environment) - The updated environment data.
 # @RETURN: Environment - The updated environment.
 @router.put("/environments/{id}", response_model=Environment)
-async def update_environment(
+async def update_environment(
     id: str,
     env: Environment,
     config_manager: ConfigManager = Depends(get_config_manager)
-):
+):
     with belief_scope("update_environment"):
         logger.info(f"[update_environment][Entry] Updating environment {id}")
     
-    # If password is masked, we need the real one for validation
-    env_to_validate = env.copy(deep=True)
+    env = env.copy(update={"url": _normalize_superset_env_url(env.url)})
+
+    # If password is masked, we need the real one for validation
+    env_to_validate = env.copy(deep=True)
     if env_to_validate.password == "********":
         old_env = next((e for e in config_manager.get_environments() if e.id == id), None)
         if old_env:
             env_to_validate.password = old_env.password
 
-    # Validate connection before updating
-    try:
-        client = SupersetClient(env_to_validate)
-        client.get_dashboards(query={"page_size": 1})
-    except Exception as e:
-        logger.error(f"[update_environment][Coherence:Failed] Connection validation failed: {e}")
-        raise HTTPException(status_code=400, detail=f"Connection validation failed: {e}")
+    # Validate connection before updating (fast path)
+    try:
+        _validate_superset_connection_fast(env_to_validate)
+    except Exception as e:
+        logger.error(f"[update_environment][Coherence:Failed] Connection validation failed: {e}")
+        raise HTTPException(status_code=400, detail=f"Connection validation failed: {e}")
 
     if config_manager.update_environment(id, env):
         return env
@@ -208,7 +244,7 @@ async def delete_environment(
 # @PARAM: id (str) - The ID of the environment to test.
 # @RETURN: dict - Success message or error.
 @router.post("/environments/{id}/test")
-async def test_environment_connection(
+async def test_environment_connection(
     id: str,
     config_manager: ConfigManager = Depends(get_config_manager)
 ):
@@ -220,15 +256,11 @@ async def test_environment_connection(
     if not env:
         raise HTTPException(status_code=404, detail=f"Environment {id} not found")
     
-    try:
-        # Initialize client (this will trigger authentication)
-        client = SupersetClient(env)
-        
-        # Try a simple request to verify
-        client.get_dashboards(query={"page_size": 1})
-        
-        logger.info(f"[test_environment_connection][Coherence:OK] Connection successful for {id}")
-        return {"status": "success", "message": "Connection successful"}
+    try:
+        _validate_superset_connection_fast(env)
+        
+        logger.info(f"[test_environment_connection][Coherence:OK] Connection successful for {id}")
+        return {"status": "success", "message": "Connection successful"}
     except Exception as e:
         logger.error(f"[test_environment_connection][Coherence:Failed] Connection failed for {id}: {e}")
         return {"status": "error", "message": str(e)}

backend/src/app.py

@@ -21,7 +21,7 @@ import asyncio
 from .dependencies import get_task_manager, get_scheduler_service
 from .core.utils.network import NetworkError
 from .core.logger import logger, belief_scope
-from .api.routes import plugins, tasks, settings, environments, mappings, migration, connections, git, storage, admin, llm, dashboards, datasets, reports, assistant
+from .api.routes import plugins, tasks, settings, environments, mappings, migration, connections, git, storage, admin, llm, dashboards, datasets, reports, assistant, clean_release
 from .api import auth
 
 # [DEF:App:Global]
@@ -133,6 +133,7 @@ app.include_router(dashboards.router)
 app.include_router(datasets.router)
 app.include_router(reports.router)
 app.include_router(assistant.router, prefix="/api/assistant", tags=["Assistant"])
+app.include_router(clean_release.router)
 
 
 # [DEF:api.include_routers:Action]
@@ -147,6 +148,21 @@ app.include_router(assistant.router, prefix="/api/assistant", tags=["Assistant"]
 # @POST: WebSocket connection is managed and logs are streamed until disconnect.
 # @TIER: CRITICAL
 # @UX_STATE: Connecting -> Streaming -> (Disconnected)
+#
+# @TEST_CONTRACT: WebSocketLogStreamApi ->
+# {
+#   required_fields: {websocket: WebSocket, task_id: str},
+#   optional_fields: {source: str, level: str},
+#   invariants: [
+#       "Accepts the WebSocket connection",
+#       "Applies source and level filters correctly to streamed logs",
+#       "Cleans up subscriptions on disconnect"
+#   ]
+# }
+# @TEST_FIXTURE: valid_ws_connection -> {"task_id": "test_1", "source": "plugin"}
+# @TEST_EDGE: task_not_found_ws -> closes connection or sends error
+# @TEST_EDGE: empty_task_logs -> waits for new logs
+# @TEST_INVARIANT: consistent_streaming -> verifies: [valid_ws_connection]
 @app.websocket("/ws/logs/{task_id}")
 async def websocket_endpoint(
     websocket: WebSocket,

backend/src/core/auth/__tests__/test_auth.py

@@ -14,6 +14,8 @@ import pytest
 from sqlalchemy import create_engine
 from sqlalchemy.orm import sessionmaker
 from src.core.database import Base
+# Import all models to ensure they are registered with Base before create_all - must import both auth and mapping to ensure Base knows about all tables
+from src.models import mapping, auth, task, report
 from src.models.auth import User, Role, Permission, ADGroupMapping
 from src.services.auth_service import AuthService
 from src.core.auth.repository import AuthRepository
@@ -176,4 +178,94 @@ def test_ad_group_mapping(auth_repo):
     assert retrieved_mapping.role_id == role.id
 
 
+def test_authenticate_user_updates_last_login(auth_service, auth_repo):
+    """@SIDE_EFFECT: authenticate_user updates last_login timestamp on success."""
+    user = User(
+        username="loginuser",
+        email="login@example.com",
+        password_hash=get_password_hash("mypassword"),
+        auth_source="LOCAL"
+    )
+    auth_repo.db.add(user)
+    auth_repo.db.commit()
+
+    assert user.last_login is None
+
+    authenticated = auth_service.authenticate_user("loginuser", "mypassword")
+    assert authenticated is not None
+    assert authenticated.last_login is not None
+
+
+def test_authenticate_inactive_user(auth_service, auth_repo):
+    """@PRE: User with is_active=False should not authenticate."""
+    user = User(
+        username="inactive_user",
+        email="inactive@example.com",
+        password_hash=get_password_hash("testpass"),
+        auth_source="LOCAL",
+        is_active=False
+    )
+    auth_repo.db.add(user)
+    auth_repo.db.commit()
+
+    result = auth_service.authenticate_user("inactive_user", "testpass")
+    assert result is None
+
+
+def test_verify_password_empty_hash():
+    """@PRE: verify_password with empty/None hash returns False."""
+    assert verify_password("anypassword", "") is False
+    assert verify_password("anypassword", None) is False
+
+
+def test_provision_adfs_user_new(auth_service, auth_repo):
+    """@POST: provision_adfs_user creates a new ADFS user with correct roles."""
+    # Set up a role and AD group mapping
+    role = Role(name="ADFS_Viewer", description="ADFS viewer role")
+    auth_repo.db.add(role)
+    auth_repo.db.commit()
+
+    mapping = ADGroupMapping(ad_group="DOMAIN\\Viewers", role_id=role.id)
+    auth_repo.db.add(mapping)
+    auth_repo.db.commit()
+
+    user_info = {
+        "upn": "newadfsuser@domain.com",
+        "email": "newadfsuser@domain.com",
+        "groups": ["DOMAIN\\Viewers"]
+    }
+
+    user = auth_service.provision_adfs_user(user_info)
+    assert user is not None
+    assert user.username == "newadfsuser@domain.com"
+    assert user.auth_source == "ADFS"
+    assert user.is_active is True
+    assert len(user.roles) == 1
+    assert user.roles[0].name == "ADFS_Viewer"
+
+
+def test_provision_adfs_user_existing(auth_service, auth_repo):
+    """@POST: provision_adfs_user updates roles for existing user."""
+    # Create existing user
+    existing = User(
+        username="existingadfs@domain.com",
+        email="existingadfs@domain.com",
+        auth_source="ADFS",
+        is_active=True
+    )
+    auth_repo.db.add(existing)
+    auth_repo.db.commit()
+
+    user_info = {
+        "upn": "existingadfs@domain.com",
+        "email": "existingadfs@domain.com",
+        "groups": []
+    }
+
+    user = auth_service.provision_adfs_user(user_info)
+    assert user is not None
+    assert user.username == "existingadfs@domain.com"
+    assert len(user.roles) == 0  # No matching group mappings
+
+
 # [/DEF:test_auth:Module]

backend/src/core/config_models.py

@@ -30,6 +30,7 @@ class Environment(BaseModel):
     url: str
     username: str
     password: str  # Will be masked in UI
+    stage: str = Field(default="DEV", pattern="^(DEV|PREPROD|PROD)$")
     verify_ssl: bool = True
     timeout: int = 30
     is_default: bool = False

backend/src/core/mapping_service.py

@@ -23,6 +23,21 @@ from src.core.logger import logger, belief_scope
 # [DEF:IdMappingService:Class]
 # @TIER: CRITICAL
 # @PURPOSE: Service handling the cataloging and retrieval of remote Superset Integer IDs.
+#
+# @TEST_CONTRACT: IdMappingServiceModel ->
+# {
+#   required_fields: {db_session: Session},
+#   invariants: [
+#       "sync_environment correctly creates or updates ResourceMapping records",
+#       "get_remote_id returns an integer or None",
+#       "get_remote_ids_batch returns a dictionary of valid UUIDs to integers"
+#   ]
+# }
+# @TEST_FIXTURE: valid_mapping_service -> {"db_session": "MockSession()"}
+# @TEST_EDGE: sync_api_failure -> handles exception gracefully
+# @TEST_EDGE: get_remote_id_not_found -> returns None
+# @TEST_EDGE: get_batch_empty_list -> returns empty dict
+# @TEST_INVARIANT: resilient_fetching -> verifies: [sync_api_failure]
 class IdMappingService:
 
     # [DEF:__init__:Function]

backend/src/core/migration/__init__.py

@@ -0,0 +1,12 @@
+# [DEF:backend.src.core.migration.__init__:Module]
+# @TIER: TRIVIAL
+# @SEMANTICS: migration, package, exports
+# @PURPOSE: Namespace package for migration pre-flight orchestration components.
+# @LAYER: Core
+
+from .dry_run_orchestrator import MigrationDryRunService
+from .archive_parser import MigrationArchiveParser
+
+__all__ = ["MigrationDryRunService", "MigrationArchiveParser"]
+
+# [/DEF:backend.src.core.migration.__init__:Module]

backend/src/core/migration/archive_parser.py

@@ -0,0 +1,139 @@
+# [DEF:backend.src.core.migration.archive_parser:Module]
+# @TIER: STANDARD
+# @SEMANTICS: migration, zip, parser, yaml, metadata
+# @PURPOSE: Parse Superset export ZIP archives into normalized object catalogs for diffing.
+# @LAYER: Core
+# @RELATION: DEPENDS_ON -> backend.src.core.logger
+# @INVARIANT: Parsing is read-only and never mutates archive files.
+
+import json
+import tempfile
+import zipfile
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+import yaml
+
+from ..logger import logger, belief_scope
+
+
+# [DEF:MigrationArchiveParser:Class]
+# @PURPOSE: Extract normalized dashboards/charts/datasets metadata from ZIP archives.
+class MigrationArchiveParser:
+    # [DEF:extract_objects_from_zip:Function]
+    # @PURPOSE: Extract object catalogs from Superset archive.
+    # @PRE: zip_path points to a valid readable ZIP.
+    # @POST: Returns object lists grouped by resource type.
+    # @RETURN: Dict[str, List[Dict[str, Any]]]
+    def extract_objects_from_zip(self, zip_path: str) -> Dict[str, List[Dict[str, Any]]]:
+        with belief_scope("MigrationArchiveParser.extract_objects_from_zip"):
+            result: Dict[str, List[Dict[str, Any]]] = {
+                "dashboards": [],
+                "charts": [],
+                "datasets": [],
+            }
+            with tempfile.TemporaryDirectory() as temp_dir_str:
+                temp_dir = Path(temp_dir_str)
+                with zipfile.ZipFile(zip_path, "r") as zip_file:
+                    zip_file.extractall(temp_dir)
+
+                result["dashboards"] = self._collect_yaml_objects(temp_dir, "dashboards")
+                result["charts"] = self._collect_yaml_objects(temp_dir, "charts")
+                result["datasets"] = self._collect_yaml_objects(temp_dir, "datasets")
+
+            return result
+    # [/DEF:extract_objects_from_zip:Function]
+
+    # [DEF:_collect_yaml_objects:Function]
+    # @PURPOSE: Read and normalize YAML manifests for one object type.
+    # @PRE: object_type is one of dashboards/charts/datasets.
+    # @POST: Returns only valid normalized objects.
+    def _collect_yaml_objects(self, root_dir: Path, object_type: str) -> List[Dict[str, Any]]:
+        with belief_scope("MigrationArchiveParser._collect_yaml_objects"):
+            files = list(root_dir.glob(f"**/{object_type}/**/*.yaml")) + list(root_dir.glob(f"**/{object_type}/*.yaml"))
+            objects: List[Dict[str, Any]] = []
+            for file_path in set(files):
+                try:
+                    with open(file_path, "r") as file_obj:
+                        payload = yaml.safe_load(file_obj) or {}
+                    normalized = self._normalize_object_payload(payload, object_type)
+                    if normalized:
+                        objects.append(normalized)
+                except Exception as exc:
+                    logger.reflect(
+                        "[MigrationArchiveParser._collect_yaml_objects][REFLECT] skip_invalid_yaml path=%s error=%s",
+                        file_path,
+                        exc,
+                    )
+            return objects
+    # [/DEF:_collect_yaml_objects:Function]
+
+    # [DEF:_normalize_object_payload:Function]
+    # @PURPOSE: Convert raw YAML payload to stable diff signature shape.
+    # @PRE: payload is parsed YAML mapping.
+    # @POST: Returns normalized descriptor with `uuid`, `title`, and `signature`.
+    def _normalize_object_payload(self, payload: Dict[str, Any], object_type: str) -> Optional[Dict[str, Any]]:
+        with belief_scope("MigrationArchiveParser._normalize_object_payload"):
+            if not isinstance(payload, dict):
+                return None
+            uuid = payload.get("uuid")
+            if not uuid:
+                return None
+
+            if object_type == "dashboards":
+                title = payload.get("dashboard_title") or payload.get("title")
+                signature = {
+                    "title": title,
+                    "slug": payload.get("slug"),
+                    "position_json": payload.get("position_json"),
+                    "json_metadata": payload.get("json_metadata"),
+                    "description": payload.get("description"),
+                    "owners": payload.get("owners"),
+                }
+                return {
+                    "uuid": str(uuid),
+                    "title": title or f"Dashboard {uuid}",
+                    "signature": json.dumps(signature, sort_keys=True, default=str),
+                    "owners": payload.get("owners") or [],
+                }
+
+            if object_type == "charts":
+                title = payload.get("slice_name") or payload.get("name")
+                signature = {
+                    "title": title,
+                    "viz_type": payload.get("viz_type"),
+                    "params": payload.get("params"),
+                    "query_context": payload.get("query_context"),
+                    "datasource_uuid": payload.get("datasource_uuid"),
+                    "dataset_uuid": payload.get("dataset_uuid"),
+                }
+                return {
+                    "uuid": str(uuid),
+                    "title": title or f"Chart {uuid}",
+                    "signature": json.dumps(signature, sort_keys=True, default=str),
+                    "dataset_uuid": payload.get("datasource_uuid") or payload.get("dataset_uuid"),
+                }
+
+            if object_type == "datasets":
+                title = payload.get("table_name") or payload.get("name")
+                signature = {
+                    "title": title,
+                    "schema": payload.get("schema"),
+                    "database_uuid": payload.get("database_uuid"),
+                    "sql": payload.get("sql"),
+                    "columns": payload.get("columns"),
+                    "metrics": payload.get("metrics"),
+                }
+                return {
+                    "uuid": str(uuid),
+                    "title": title or f"Dataset {uuid}",
+                    "signature": json.dumps(signature, sort_keys=True, default=str),
+                    "database_uuid": payload.get("database_uuid"),
+                }
+
+            return None
+    # [/DEF:_normalize_object_payload:Function]
+
+
+# [/DEF:MigrationArchiveParser:Class]
+# [/DEF:backend.src.core.migration.archive_parser:Module]

backend/src/core/migration/dry_run_orchestrator.py

@@ -0,0 +1,235 @@
+# [DEF:backend.src.core.migration.dry_run_orchestrator:Module]
+# @TIER: STANDARD
+# @SEMANTICS: migration, dry_run, diff, risk, superset
+# @PURPOSE: Compute pre-flight migration diff and risk scoring without apply.
+# @LAYER: Core
+# @RELATION: DEPENDS_ON -> backend.src.core.superset_client
+# @RELATION: DEPENDS_ON -> backend.src.core.migration_engine
+# @RELATION: DEPENDS_ON -> backend.src.core.migration.archive_parser
+# @RELATION: DEPENDS_ON -> backend.src.core.migration.risk_assessor
+# @INVARIANT: Dry run is informative only and must not mutate target environment.
+
+from datetime import datetime, timezone
+import json
+from typing import Any, Dict, List
+
+from sqlalchemy.orm import Session
+
+from ...models.dashboard import DashboardSelection
+from ...models.mapping import DatabaseMapping
+from ..logger import logger, belief_scope
+from .archive_parser import MigrationArchiveParser
+from .risk_assessor import build_risks, score_risks
+from ..migration_engine import MigrationEngine
+from ..superset_client import SupersetClient
+from ..utils.fileio import create_temp_file
+
+
+# [DEF:MigrationDryRunService:Class]
+# @PURPOSE: Build deterministic diff/risk payload for migration pre-flight.
+class MigrationDryRunService:
+    # [DEF:__init__:Function]
+    # @PURPOSE: Wire parser dependency for archive object extraction.
+    # @PRE: parser can be omitted to use default implementation.
+    # @POST: Service is ready to calculate dry-run payload.
+    def __init__(self, parser: MigrationArchiveParser | None = None):
+        self.parser = parser or MigrationArchiveParser()
+    # [/DEF:__init__:Function]
+
+    # [DEF:run:Function]
+    # @PURPOSE: Execute full dry-run computation for selected dashboards.
+    # @PRE: source/target clients are authenticated and selection validated by caller.
+    # @POST: Returns JSON-serializable pre-flight payload with summary, diff and risk.
+    # @SIDE_EFFECT: Reads source export archives and target metadata via network.
+    def run(
+        self,
+        selection: DashboardSelection,
+        source_client: SupersetClient,
+        target_client: SupersetClient,
+        db: Session,
+    ) -> Dict[str, Any]:
+        with belief_scope("MigrationDryRunService.run"):
+            logger.explore("[MigrationDryRunService.run][EXPLORE] starting dry-run pipeline")
+            engine = MigrationEngine()
+            db_mapping = self._load_db_mapping(db, selection) if selection.replace_db_config else {}
+            transformed = {"dashboards": {}, "charts": {}, "datasets": {}}
+
+            dashboards_preview = source_client.get_dashboards_summary()
+            selected_preview = {
+                item["id"]: item
+                for item in dashboards_preview
+                if item.get("id") in selection.selected_ids
+            }
+
+            for dashboard_id in selection.selected_ids:
+                exported_content, _ = source_client.export_dashboard(int(dashboard_id))
+                with create_temp_file(content=exported_content, suffix=".zip") as source_zip:
+                    with create_temp_file(suffix=".zip") as transformed_zip:
+                        success = engine.transform_zip(
+                            str(source_zip),
+                            str(transformed_zip),
+                            db_mapping,
+                            strip_databases=False,
+                            target_env_id=selection.target_env_id,
+                            fix_cross_filters=selection.fix_cross_filters,
+                        )
+                        if not success:
+                            raise ValueError(f"Failed to transform export archive for dashboard {dashboard_id}")
+                        extracted = self.parser.extract_objects_from_zip(str(transformed_zip))
+                        self._accumulate_objects(transformed, extracted)
+
+            source_objects = {key: list(value.values()) for key, value in transformed.items()}
+            target_objects = self._build_target_signatures(target_client)
+            diff = {
+                "dashboards": self._build_object_diff(source_objects["dashboards"], target_objects["dashboards"]),
+                "charts": self._build_object_diff(source_objects["charts"], target_objects["charts"]),
+                "datasets": self._build_object_diff(source_objects["datasets"], target_objects["datasets"]),
+            }
+            risk = self._build_risks(source_objects, target_objects, diff, target_client)
+
+            summary = {
+                "dashboards": {action: len(diff["dashboards"][action]) for action in ("create", "update", "delete")},
+                "charts": {action: len(diff["charts"][action]) for action in ("create", "update", "delete")},
+                "datasets": {action: len(diff["datasets"][action]) for action in ("create", "update", "delete")},
+                "selected_dashboards": len(selection.selected_ids),
+            }
+            selected_titles = [
+                selected_preview[dash_id]["title"]
+                for dash_id in selection.selected_ids
+                if dash_id in selected_preview
+            ]
+
+            logger.reason("[MigrationDryRunService.run][REASON] dry-run payload assembled")
+            return {
+                "generated_at": datetime.now(timezone.utc).isoformat(),
+                "selection": selection.model_dump(),
+                "selected_dashboard_titles": selected_titles,
+                "diff": diff,
+                "summary": summary,
+                "risk": score_risks(risk),
+            }
+    # [/DEF:run:Function]
+
+    # [DEF:_load_db_mapping:Function]
+    # @PURPOSE: Resolve UUID mapping for optional DB config replacement.
+    def _load_db_mapping(self, db: Session, selection: DashboardSelection) -> Dict[str, str]:
+        rows = db.query(DatabaseMapping).filter(
+            DatabaseMapping.source_env_id == selection.source_env_id,
+            DatabaseMapping.target_env_id == selection.target_env_id,
+        ).all()
+        return {row.source_db_uuid: row.target_db_uuid for row in rows}
+    # [/DEF:_load_db_mapping:Function]
+
+    # [DEF:_accumulate_objects:Function]
+    # @PURPOSE: Merge extracted resources by UUID to avoid duplicates.
+    def _accumulate_objects(self, target: Dict[str, Dict[str, Dict[str, Any]]], source: Dict[str, List[Dict[str, Any]]]) -> None:
+        for object_type in ("dashboards", "charts", "datasets"):
+            for item in source.get(object_type, []):
+                uuid = item.get("uuid")
+                if uuid:
+                    target[object_type][str(uuid)] = item
+    # [/DEF:_accumulate_objects:Function]
+
+    # [DEF:_index_by_uuid:Function]
+    # @PURPOSE: Build UUID-index map for normalized resources.
+    def _index_by_uuid(self, objects: List[Dict[str, Any]]) -> Dict[str, Dict[str, Any]]:
+        indexed: Dict[str, Dict[str, Any]] = {}
+        for obj in objects:
+            uuid = obj.get("uuid")
+            if uuid:
+                indexed[str(uuid)] = obj
+        return indexed
+    # [/DEF:_index_by_uuid:Function]
+
+    # [DEF:_build_object_diff:Function]
+    # @PURPOSE: Compute create/update/delete buckets by UUID+signature.
+    def _build_object_diff(self, source_objects: List[Dict[str, Any]], target_objects: List[Dict[str, Any]]) -> Dict[str, List[Dict[str, Any]]]:
+        target_index = self._index_by_uuid(target_objects)
+        created: List[Dict[str, Any]] = []
+        updated: List[Dict[str, Any]] = []
+        deleted: List[Dict[str, Any]] = []
+        for source_obj in source_objects:
+            source_uuid = str(source_obj.get("uuid"))
+            target_obj = target_index.get(source_uuid)
+            if not target_obj:
+                created.append({"uuid": source_uuid, "title": source_obj.get("title")})
+                continue
+            if source_obj.get("signature") != target_obj.get("signature"):
+                updated.append({
+                    "uuid": source_uuid,
+                    "title": source_obj.get("title"),
+                    "target_title": target_obj.get("title"),
+                })
+        return {"create": created, "update": updated, "delete": deleted}
+    # [/DEF:_build_object_diff:Function]
+
+    # [DEF:_build_target_signatures:Function]
+    # @PURPOSE: Pull target metadata and normalize it into comparable signatures.
+    def _build_target_signatures(self, client: SupersetClient) -> Dict[str, List[Dict[str, Any]]]:
+        _, dashboards = client.get_dashboards(query={
+            "columns": ["uuid", "dashboard_title", "slug", "position_json", "json_metadata", "description", "owners"],
+        })
+        _, datasets = client.get_datasets(query={
+            "columns": ["uuid", "table_name", "schema", "database_uuid", "sql", "columns", "metrics"],
+        })
+        _, charts = client.get_charts(query={
+            "columns": ["uuid", "slice_name", "viz_type", "params", "query_context", "datasource_uuid", "dataset_uuid"],
+        })
+        return {
+            "dashboards": [{
+                "uuid": str(item.get("uuid")),
+                "title": item.get("dashboard_title"),
+                "owners": item.get("owners") or [],
+                "signature": json.dumps({
+                    "title": item.get("dashboard_title"),
+                    "slug": item.get("slug"),
+                    "position_json": item.get("position_json"),
+                    "json_metadata": item.get("json_metadata"),
+                    "description": item.get("description"),
+                    "owners": item.get("owners"),
+                }, sort_keys=True, default=str),
+            } for item in dashboards if item.get("uuid")],
+            "datasets": [{
+                "uuid": str(item.get("uuid")),
+                "title": item.get("table_name"),
+                "database_uuid": item.get("database_uuid"),
+                "signature": json.dumps({
+                    "title": item.get("table_name"),
+                    "schema": item.get("schema"),
+                    "database_uuid": item.get("database_uuid"),
+                    "sql": item.get("sql"),
+                    "columns": item.get("columns"),
+                    "metrics": item.get("metrics"),
+                }, sort_keys=True, default=str),
+            } for item in datasets if item.get("uuid")],
+            "charts": [{
+                "uuid": str(item.get("uuid")),
+                "title": item.get("slice_name") or item.get("name"),
+                "dataset_uuid": item.get("datasource_uuid") or item.get("dataset_uuid"),
+                "signature": json.dumps({
+                    "title": item.get("slice_name") or item.get("name"),
+                    "viz_type": item.get("viz_type"),
+                    "params": item.get("params"),
+                    "query_context": item.get("query_context"),
+                    "datasource_uuid": item.get("datasource_uuid"),
+                    "dataset_uuid": item.get("dataset_uuid"),
+                }, sort_keys=True, default=str),
+            } for item in charts if item.get("uuid")],
+        }
+    # [/DEF:_build_target_signatures:Function]
+
+    # [DEF:_build_risks:Function]
+    # @PURPOSE: Build risk items for missing datasource, broken refs, overwrite, owner mismatch.
+    def _build_risks(
+        self,
+        source_objects: Dict[str, List[Dict[str, Any]]],
+        target_objects: Dict[str, List[Dict[str, Any]]],
+        diff: Dict[str, Dict[str, List[Dict[str, Any]]]],
+        target_client: SupersetClient,
+    ) -> List[Dict[str, Any]]:
+        return build_risks(source_objects, target_objects, diff, target_client)
+    # [/DEF:_build_risks:Function]
+
+
+# [/DEF:MigrationDryRunService:Class]
+# [/DEF:backend.src.core.migration.dry_run_orchestrator:Module]

backend/src/core/migration/risk_assessor.py

@@ -0,0 +1,119 @@
+# [DEF:backend.src.core.migration.risk_assessor:Module]
+# @TIER: STANDARD
+# @SEMANTICS: migration, dry_run, risk, scoring
+# @PURPOSE: Risk evaluation helpers for migration pre-flight reporting.
+# @LAYER: Core
+# @RELATION: USED_BY -> backend.src.core.migration.dry_run_orchestrator
+
+from typing import Any, Dict, List
+
+from ..superset_client import SupersetClient
+
+
+# [DEF:index_by_uuid:Function]
+# @PURPOSE: Build UUID-index from normalized objects.
+def index_by_uuid(objects: List[Dict[str, Any]]) -> Dict[str, Dict[str, Any]]:
+    indexed: Dict[str, Dict[str, Any]] = {}
+    for obj in objects:
+        uuid = obj.get("uuid")
+        if uuid:
+            indexed[str(uuid)] = obj
+    return indexed
+# [/DEF:index_by_uuid:Function]
+
+
+# [DEF:extract_owner_identifiers:Function]
+# @PURPOSE: Normalize owner payloads for stable comparison.
+def extract_owner_identifiers(owners: Any) -> List[str]:
+    if not isinstance(owners, list):
+        return []
+    ids: List[str] = []
+    for owner in owners:
+        if isinstance(owner, dict):
+            if owner.get("username"):
+                ids.append(str(owner["username"]))
+            elif owner.get("id") is not None:
+                ids.append(str(owner["id"]))
+        elif owner is not None:
+            ids.append(str(owner))
+    return sorted(set(ids))
+# [/DEF:extract_owner_identifiers:Function]
+
+
+# [DEF:build_risks:Function]
+# @PURPOSE: Build risk list from computed diffs and target catalog state.
+def build_risks(
+    source_objects: Dict[str, List[Dict[str, Any]]],
+    target_objects: Dict[str, List[Dict[str, Any]]],
+    diff: Dict[str, Dict[str, List[Dict[str, Any]]]],
+    target_client: SupersetClient,
+) -> List[Dict[str, Any]]:
+    risks: List[Dict[str, Any]] = []
+    for object_type in ("dashboards", "charts", "datasets"):
+        for item in diff[object_type]["update"]:
+            risks.append({
+                "code": "overwrite_existing",
+                "severity": "medium",
+                "object_type": object_type[:-1],
+                "object_uuid": item["uuid"],
+                "message": f"Object will be updated in target: {item.get('title') or item['uuid']}",
+            })
+
+    target_dataset_uuids = set(index_by_uuid(target_objects["datasets"]).keys())
+    _, target_databases = target_client.get_databases(query={"columns": ["uuid"]})
+    target_database_uuids = {str(item.get("uuid")) for item in target_databases if item.get("uuid")}
+
+    for dataset in source_objects["datasets"]:
+        db_uuid = dataset.get("database_uuid")
+        if db_uuid and str(db_uuid) not in target_database_uuids:
+            risks.append({
+                "code": "missing_datasource",
+                "severity": "high",
+                "object_type": "dataset",
+                "object_uuid": dataset.get("uuid"),
+                "message": f"Target datasource is missing for dataset {dataset.get('title') or dataset.get('uuid')}",
+            })
+
+    for chart in source_objects["charts"]:
+        ds_uuid = chart.get("dataset_uuid")
+        if ds_uuid and str(ds_uuid) not in target_dataset_uuids:
+            risks.append({
+                "code": "breaking_reference",
+                "severity": "high",
+                "object_type": "chart",
+                "object_uuid": chart.get("uuid"),
+                "message": f"Chart references dataset not found on target: {ds_uuid}",
+            })
+
+    source_dash = index_by_uuid(source_objects["dashboards"])
+    target_dash = index_by_uuid(target_objects["dashboards"])
+    for item in diff["dashboards"]["update"]:
+        source_obj = source_dash.get(item["uuid"])
+        target_obj = target_dash.get(item["uuid"])
+        if not source_obj or not target_obj:
+            continue
+        source_owners = extract_owner_identifiers(source_obj.get("owners"))
+        target_owners = extract_owner_identifiers(target_obj.get("owners"))
+        if source_owners and target_owners and source_owners != target_owners:
+            risks.append({
+                "code": "owner_mismatch",
+                "severity": "low",
+                "object_type": "dashboard",
+                "object_uuid": item["uuid"],
+                "message": f"Owner mismatch for dashboard {item.get('title') or item['uuid']}",
+            })
+    return risks
+# [/DEF:build_risks:Function]
+
+
+# [DEF:score_risks:Function]
+# @PURPOSE: Aggregate risk list into score and level.
+def score_risks(risk_items: List[Dict[str, Any]]) -> Dict[str, Any]:
+    weights = {"high": 25, "medium": 10, "low": 5}
+    score = min(100, sum(weights.get(item.get("severity", "low"), 5) for item in risk_items))
+    level = "low" if score < 25 else "medium" if score < 60 else "high"
+    return {"score": score, "level": level, "items": risk_items}
+# [/DEF:score_risks:Function]
+
+
+# [/DEF:backend.src.core.migration.risk_assessor:Module]

backend/src/core/superset_client.py

@@ -14,7 +14,7 @@ import json
 import re
 import zipfile
 from pathlib import Path
-from typing import Dict, List, Optional, Tuple, Union, cast
+from typing import Any, Dict, List, Optional, Tuple, Union, cast
 from requests import Response
 from datetime import datetime
 from .logger import logger as app_logger, belief_scope
@@ -87,7 +87,18 @@ class SupersetClient:
             app_logger.info("[get_dashboards][Enter] Fetching dashboards.")
             validated_query = self._validate_query_params(query or {})
             if 'columns' not in validated_query:
-                validated_query['columns'] = ["slug", "id", "changed_on_utc", "dashboard_title", "published"]
+                validated_query['columns'] = [
+                    "slug",
+                    "id",
+                    "url",
+                    "changed_on_utc",
+                    "dashboard_title",
+                    "published",
+                    "created_by",
+                    "changed_by",
+                    "changed_by_name",
+                    "owners",
+                ]
             
             paginated_data = self._fetch_all_pages(
                 endpoint="/dashboard/",
@@ -98,6 +109,42 @@ class SupersetClient:
             return total_count, paginated_data
     # [/DEF:get_dashboards:Function]
 
+    # [DEF:get_dashboards_page:Function]
+    # @PURPOSE: Fetches a single dashboards page from Superset without iterating all pages.
+    # @PARAM: query (Optional[Dict]) - Query with page/page_size and optional columns.
+    # @PRE: Client is authenticated.
+    # @POST: Returns total count and one page of dashboards.
+    # @RETURN: Tuple[int, List[Dict]]
+    def get_dashboards_page(self, query: Optional[Dict] = None) -> Tuple[int, List[Dict]]:
+        with belief_scope("get_dashboards_page"):
+            validated_query = self._validate_query_params(query or {})
+            if "columns" not in validated_query:
+                validated_query["columns"] = [
+                    "slug",
+                    "id",
+                    "url",
+                    "changed_on_utc",
+                    "dashboard_title",
+                    "published",
+                    "created_by",
+                    "changed_by",
+                    "changed_by_name",
+                    "owners",
+                ]
+
+            response_json = cast(
+                Dict[str, Any],
+                self.network.request(
+                    method="GET",
+                    endpoint="/dashboard/",
+                    params={"q": json.dumps(validated_query)},
+                ),
+            )
+            result = response_json.get("result", [])
+            total_count = response_json.get("count", len(result))
+            return total_count, result
+    # [/DEF:get_dashboards_page:Function]
+
     # [DEF:get_dashboards_summary:Function]
     # @PURPOSE: Fetches dashboard metadata optimized for the grid.
     # @PRE: Client is authenticated.
@@ -105,23 +152,171 @@ class SupersetClient:
     # @RETURN: List[Dict]
     def get_dashboards_summary(self) -> List[Dict]:
         with belief_scope("SupersetClient.get_dashboards_summary"):
-            query = {
-                "columns": ["id", "dashboard_title", "changed_on_utc", "published"]
-            }
+            # Rely on list endpoint default projection to stay compatible
+            # across Superset versions and preserve owners in one request.
+            query: Dict[str, Any] = {}
             _, dashboards = self.get_dashboards(query=query)
 
             # Map fields to DashboardMetadata schema
             result = []
             for dash in dashboards:
+                owners = self._extract_owner_labels(dash.get("owners"))
+                # No per-dashboard detail requests here: keep list endpoint O(1).
+                if not owners:
+                    owners = self._extract_owner_labels(
+                        [dash.get("created_by"), dash.get("changed_by")],
+                    )
+
                 result.append({
                     "id": dash.get("id"),
+                    "slug": dash.get("slug"),
                     "title": dash.get("dashboard_title"),
+                    "url": dash.get("url"),
                     "last_modified": dash.get("changed_on_utc"),
-                    "status": "published" if dash.get("published") else "draft"
+                    "status": "published" if dash.get("published") else "draft",
+                    "created_by": self._extract_user_display(
+                        None,
+                        dash.get("created_by"),
+                    ),
+                    "modified_by": self._extract_user_display(
+                        dash.get("changed_by_name"),
+                        dash.get("changed_by"),
+                    ),
+                    "owners": owners,
                 })
             return result
     # [/DEF:get_dashboards_summary:Function]
 
+    # [DEF:get_dashboards_summary_page:Function]
+    # @PURPOSE: Fetches one page of dashboard metadata optimized for the grid.
+    # @PARAM: page (int) - 1-based page number from API route contract.
+    # @PARAM: page_size (int) - Number of items per page.
+    # @PRE: page >= 1 and page_size > 0.
+    # @POST: Returns mapped summaries and total dashboard count.
+    # @RETURN: Tuple[int, List[Dict]]
+    def get_dashboards_summary_page(
+        self,
+        page: int,
+        page_size: int,
+        search: Optional[str] = None,
+    ) -> Tuple[int, List[Dict]]:
+        with belief_scope("SupersetClient.get_dashboards_summary_page"):
+            query: Dict[str, Any] = {
+                "page": max(page - 1, 0),
+                "page_size": page_size,
+            }
+            normalized_search = (search or "").strip()
+            if normalized_search:
+                # Superset list API supports filter objects with `opr` operator.
+                # `ct` -> contains (ILIKE on most Superset backends).
+                query["filters"] = [
+                    {
+                        "col": "dashboard_title",
+                        "opr": "ct",
+                        "value": normalized_search,
+                    }
+                ]
+
+            total_count, dashboards = self.get_dashboards_page(query=query)
+
+            result = []
+            for dash in dashboards:
+                owners = self._extract_owner_labels(dash.get("owners"))
+                if not owners:
+                    owners = self._extract_owner_labels(
+                        [dash.get("created_by"), dash.get("changed_by")],
+                    )
+
+                result.append({
+                    "id": dash.get("id"),
+                    "slug": dash.get("slug"),
+                    "title": dash.get("dashboard_title"),
+                    "url": dash.get("url"),
+                    "last_modified": dash.get("changed_on_utc"),
+                    "status": "published" if dash.get("published") else "draft",
+                    "created_by": self._extract_user_display(
+                        None,
+                        dash.get("created_by"),
+                    ),
+                    "modified_by": self._extract_user_display(
+                        dash.get("changed_by_name"),
+                        dash.get("changed_by"),
+                    ),
+                    "owners": owners,
+                })
+
+            return total_count, result
+    # [/DEF:get_dashboards_summary_page:Function]
+
+    # [DEF:_extract_owner_labels:Function]
+    # @PURPOSE: Normalize dashboard owners payload to stable display labels.
+    # @PRE: owners payload can be scalar, object or list.
+    # @POST: Returns deduplicated non-empty owner labels preserving order.
+    # @RETURN: List[str]
+    def _extract_owner_labels(self, owners_payload: Any) -> List[str]:
+        if owners_payload is None:
+            return []
+
+        owners_list: List[Any]
+        if isinstance(owners_payload, list):
+            owners_list = owners_payload
+        else:
+            owners_list = [owners_payload]
+
+        normalized: List[str] = []
+        for owner in owners_list:
+            label: Optional[str] = None
+            if isinstance(owner, dict):
+                label = self._extract_user_display(None, owner)
+            else:
+                label = self._sanitize_user_text(owner)
+            if label and label not in normalized:
+                normalized.append(label)
+        return normalized
+    # [/DEF:_extract_owner_labels:Function]
+
+    # [DEF:_extract_user_display:Function]
+    # @PURPOSE: Normalize user payload to a stable display name.
+    # @PRE: user payload can be string, dict or None.
+    # @POST: Returns compact non-empty display value or None.
+    # @RETURN: Optional[str]
+    def _extract_user_display(self, preferred_value: Optional[str], user_payload: Optional[Dict]) -> Optional[str]:
+        preferred = self._sanitize_user_text(preferred_value)
+        if preferred:
+            return preferred
+
+        if isinstance(user_payload, dict):
+            full_name = self._sanitize_user_text(user_payload.get("full_name"))
+            if full_name:
+                return full_name
+            first_name = self._sanitize_user_text(user_payload.get("first_name")) or ""
+            last_name = self._sanitize_user_text(user_payload.get("last_name")) or ""
+            combined = " ".join(part for part in [first_name, last_name] if part).strip()
+            if combined:
+                return combined
+            username = self._sanitize_user_text(user_payload.get("username"))
+            if username:
+                return username
+            email = self._sanitize_user_text(user_payload.get("email"))
+            if email:
+                return email
+        return None
+    # [/DEF:_extract_user_display:Function]
+
+    # [DEF:_sanitize_user_text:Function]
+    # @PURPOSE: Convert scalar value to non-empty user-facing text.
+    # @PRE: value can be any scalar type.
+    # @POST: Returns trimmed string or None.
+    # @RETURN: Optional[str]
+    def _sanitize_user_text(self, value: Optional[Union[str, int]]) -> Optional[str]:
+        if value is None:
+            return None
+        normalized = str(value).strip()
+        if not normalized:
+            return None
+        return normalized
+    # [/DEF:_sanitize_user_text:Function]
+
     # [DEF:get_dashboard:Function]
     # @PURPOSE: Fetches a single dashboard by ID.
     # @PRE: Client is authenticated and dashboard_id exists.
@@ -336,6 +531,25 @@ class SupersetClient:
             }
     # [/DEF:get_dashboard_detail:Function]
 
+    # [DEF:get_charts:Function]
+    # @PURPOSE: Fetches all charts with pagination support.
+    # @PARAM: query (Optional[Dict]) - Optional query params/columns/filters.
+    # @PRE: Client is authenticated.
+    # @POST: Returns total count and charts list.
+    # @RETURN: Tuple[int, List[Dict]]
+    def get_charts(self, query: Optional[Dict] = None) -> Tuple[int, List[Dict]]:
+        with belief_scope("get_charts"):
+            validated_query = self._validate_query_params(query or {})
+            if "columns" not in validated_query:
+                validated_query["columns"] = ["id", "uuid", "slice_name", "viz_type"]
+
+            paginated_data = self._fetch_all_pages(
+                endpoint="/chart/",
+                pagination_options={"base_query": validated_query, "results_field": "result"},
+            )
+            return len(paginated_data), paginated_data
+    # [/DEF:get_charts:Function]
+
     # [DEF:_extract_chart_ids_from_layout:Function]
     # @PURPOSE: Traverses dashboard layout metadata and extracts chart IDs from common keys.
     # @PRE: payload can be dict/list/scalar.

backend/src/core/task_manager/context.py

@@ -19,6 +19,20 @@ from ..logger import belief_scope
 # @TIER: CRITICAL
 # @INVARIANT: logger is always a valid TaskLogger instance.
 # @UX_STATE: Idle -> Active -> Complete
+#
+# @TEST_CONTRACT: TaskContextInit ->
+# {
+#   required_fields: {task_id: str, add_log_fn: Callable, params: dict},
+#   optional_fields: {default_source: str},
+#   invariants: [
+#       "task_id matches initialized logger's task_id",
+#       "logger is a valid TaskLogger instance"
+#   ]
+# }
+# @TEST_FIXTURE: valid_context -> {"task_id": "123", "add_log_fn": lambda *args: None, "params": {"k": "v"}, "default_source": "plugin"}
+# @TEST_EDGE: missing_task_id -> raises TypeError
+# @TEST_EDGE: missing_add_log_fn -> raises TypeError
+# @TEST_INVARIANT: logger_initialized -> verifies: [valid_context]
 class TaskContext:
     """
     Execution context provided to plugins during task execution.

backend/src/core/task_manager/manager.py

@@ -39,17 +39,21 @@ from ..logger import logger, belief_scope, should_log_task_level
 # @INVARIANT: Task IDs are unique within the registry.
 # @INVARIANT: Each task has exactly one status at any time.
 # @INVARIANT: Log entries are never deleted after being added to a task.
-# @TEST_CONTRACT: TaskManager -> {
-#    required_fields: {plugin_id: str, params: dict},
-#    optional_fields: {user_id: str},
-#    invariants: ["Task IDs are unique within the registry", "Each task has exactly one status at any time"]
+#
+# @TEST_CONTRACT: TaskManagerModel ->
+# {
+#   required_fields: {plugin_loader: PluginLoader},
+#   invariants: [
+#       "Tasks are persisted immediately upon creation",
+#       "Running tasks use a thread pool or asyncio event loop based on executor type",
+#       "Log flushing runs on a background thread"
+#   ]
 # }
-# @TEST_FIXTURE: create_valid_task -> {"plugin_id": "migration_plugin", "params": {"source": "A", "target": "B"}}
-# @TEST_EDGE: missing_required_field -> {"plugin_id": null}
-# @TEST_EDGE: empty_response -> {"params": {}}
-# @TEST_EDGE: invalid_type -> {"params": "string_instead_of_dict"}
-# @TEST_EDGE: external_failure -> {"plugin_not_found": true}
-# @TEST_INVARIANT: single_status -> verifies: [create_valid_task, external_failure]
+# @TEST_FIXTURE: valid_manager -> {"plugin_loader": "MockPluginLoader()"}
+# @TEST_EDGE: create_task_invalid_plugin -> raises ValueError
+# @TEST_EDGE: create_task_invalid_params -> raises ValueError
+# @TEST_INVARIANT: lifecycle_management -> verifies: [valid_manager]
+class TaskManager:
     """
     Manages the lifecycle of tasks, including their creation, execution, and state tracking.
     """

backend/src/core/task_manager/models.py

@@ -45,6 +45,14 @@ class LogLevel(str, Enum):
 # @PURPOSE: A Pydantic model representing a single, structured log entry associated with a task.
 # @TIER: CRITICAL
 # @INVARIANT: Each log entry has a unique timestamp and source.
+#
+# @TEST_CONTRACT: LogEntryModel ->
+# {
+#   required_fields: {message: str},
+#   optional_fields: {timestamp: datetime, level: str, source: str, context: dict, metadata: dict}
+# }
+# @TEST_FIXTURE: valid_log_entry -> {"message": "Plugin initialized"}
+# @TEST_EDGE: empty_message -> {"message": ""}
 class LogEntry(BaseModel):
     timestamp: datetime = Field(default_factory=datetime.utcnow)
     level: str = Field(default="INFO")

backend/src/core/task_manager/persistence.py

@@ -24,6 +24,20 @@ from ..logger import logger, belief_scope
 # @SEMANTICS: persistence, service, database, sqlalchemy
 # @PURPOSE: Provides methods to save and load tasks from the tasks.db database using SQLAlchemy.
 # @INVARIANT: Persistence must handle potentially missing task fields natively.
+#
+# @TEST_CONTRACT: TaskPersistenceService ->
+# {
+#   required_fields: {},
+#   invariants: [
+#       "persist_task creates or updates a record",
+#       "load_tasks retrieves valid Task instances",
+#       "delete_tasks correctly removes records from the database"
+#   ]
+# }
+# @TEST_FIXTURE: valid_task_persistence -> {"task_id": "123", "status": "PENDING"}
+# @TEST_EDGE: persist_invalid_task_type -> raises Exception
+# @TEST_EDGE: load_corrupt_json_params -> handled gracefully
+# @TEST_INVARIANT: accurate_round_trip -> verifies: [valid_task_persistence, load_corrupt_json_params]
 class TaskPersistenceService:
     # [DEF:_json_load_if_needed:Function]
     # @PURPOSE: Safely load JSON strings from DB if necessary
@@ -245,6 +259,19 @@ class TaskPersistenceService:
 # @TIER: CRITICAL
 # @RELATION: DEPENDS_ON -> TaskLogRecord
 # @INVARIANT: Log entries are batch-inserted for performance.
+#
+# @TEST_CONTRACT: TaskLogPersistenceService ->
+# {
+#   required_fields: {},
+#   invariants: [
+#       "add_logs efficiently saves logs to the database",
+#       "get_logs retrieves properly filtered LogEntry objects"
+#   ]
+# }
+# @TEST_FIXTURE: valid_log_batch -> {"task_id": "123", "logs": [{"level": "INFO", "message": "msg"}]}
+# @TEST_EDGE: empty_log_list -> no-op behavior
+# @TEST_EDGE: add_logs_db_error -> rollback and log error
+# @TEST_INVARIANT: accurate_log_aggregation -> verifies: [valid_log_batch]
 class TaskLogPersistenceService:
     """
     Service for persisting and querying task logs.

backend/src/core/task_manager/task_logger.py

@@ -15,8 +15,21 @@ from typing import Dict, Any, Optional, Callable
 # @PURPOSE: A wrapper around TaskManager._add_log that carries task_id and source context.
 # @TIER: CRITICAL
 # @INVARIANT: All log calls include the task_id and source.
-# @TEST_DATA: task_logger -> {"task_id": "test_123", "source": "test_plugin"}
 # @UX_STATE: Idle -> Logging -> (system records log)
+#
+# @TEST_CONTRACT: TaskLoggerModel ->
+# {
+#   required_fields: {task_id: str, add_log_fn: Callable},
+#   optional_fields: {source: str},
+#   invariants: [
+#       "All specific log methods (info, error) delegate to _log",
+#       "with_source creates a new logger with the same task_id"
+#   ]
+# }
+# @TEST_FIXTURE: valid_task_logger -> {"task_id": "test_123", "add_log_fn": lambda *args: None, "source": "test_plugin"}
+# @TEST_EDGE: missing_task_id -> raises TypeError
+# @TEST_EDGE: invalid_add_log_fn -> raises TypeError
+# @TEST_INVARIANT: consistent_delegation -> verifies: [valid_task_logger]
 class TaskLogger:
     """
     A dedicated logger for tasks that automatically tags logs with source attribution.

backend/src/core/utils/network.py

@@ -101,7 +101,8 @@ class APIClient:
     def __init__(self, config: Dict[str, Any], verify_ssl: bool = True, timeout: int = DEFAULT_TIMEOUT):
         with belief_scope("__init__"):
             app_logger.info("[APIClient.__init__][Entry] Initializing APIClient.")
-        self.base_url: str = config.get("base_url", "")
+        self.base_url: str = self._normalize_base_url(config.get("base_url", ""))
+        self.api_base_url: str = f"{self.base_url}/api/v1"
         self.auth = config.get("auth")
         self.request_settings = {"verify_ssl": verify_ssl, "timeout": timeout}
         self.session = self._init_session()
@@ -156,6 +157,34 @@ class APIClient:
         return session
     # [/DEF:_init_session:Function]
 
+    # [DEF:_normalize_base_url:Function]
+    # @PURPOSE: Normalize Superset environment URL to base host/path without trailing slash and /api/v1 suffix.
+    # @PRE: raw_url can be empty.
+    # @POST: Returns canonical base URL suitable for building API endpoints.
+    # @RETURN: str
+    def _normalize_base_url(self, raw_url: str) -> str:
+        normalized = str(raw_url or "").strip().rstrip("/")
+        if normalized.lower().endswith("/api/v1"):
+            normalized = normalized[:-len("/api/v1")]
+        return normalized.rstrip("/")
+    # [/DEF:_normalize_base_url:Function]
+
+    # [DEF:_build_api_url:Function]
+    # @PURPOSE: Build absolute Superset API URL for endpoint using canonical /api/v1 base.
+    # @PRE: endpoint is relative path or absolute URL.
+    # @POST: Returns full URL without accidental duplicate slashes.
+    # @RETURN: str
+    def _build_api_url(self, endpoint: str) -> str:
+        normalized_endpoint = str(endpoint or "").strip()
+        if normalized_endpoint.startswith("http://") or normalized_endpoint.startswith("https://"):
+            return normalized_endpoint
+        if not normalized_endpoint.startswith("/"):
+            normalized_endpoint = f"/{normalized_endpoint}"
+        if normalized_endpoint.startswith("/api/v1/") or normalized_endpoint == "/api/v1":
+            return f"{self.base_url}{normalized_endpoint}"
+        return f"{self.api_base_url}{normalized_endpoint}"
+    # [/DEF:_build_api_url:Function]
+
     # [DEF:authenticate:Function]
     # @PURPOSE: Выполняет аутентификацию в Superset API и получает access и CSRF токены.
     # @PRE: self.auth and self.base_url must be valid.
@@ -166,7 +195,7 @@ class APIClient:
         with belief_scope("authenticate"):
             app_logger.info("[authenticate][Enter] Authenticating to %s", self.base_url)
             try:
-                login_url = f"{self.base_url}/security/login"
+                login_url = f"{self.api_base_url}/security/login"
                 # Log the payload keys and values (masking password)
                 masked_auth = {k: ("******" if k == "password" else v) for k, v in self.auth.items()}
                 app_logger.info(f"[authenticate][Debug] Login URL: {login_url}")
@@ -180,7 +209,7 @@ class APIClient:
                 response.raise_for_status()
                 access_token = response.json()["access_token"]
                 
-                csrf_url = f"{self.base_url}/security/csrf_token/"
+                csrf_url = f"{self.api_base_url}/security/csrf_token/"
                 csrf_response = self.session.get(csrf_url, headers={"Authorization": f"Bearer {access_token}"}, timeout=self.request_settings["timeout"])
                 csrf_response.raise_for_status()
                 
@@ -224,7 +253,7 @@ class APIClient:
     # @RETURN: `requests.Response` если `raw_response=True`, иначе `dict`.
     # @THROW: SupersetAPIError, NetworkError и их подклассы.
     def request(self, method: str, endpoint: str, headers: Optional[Dict] = None, raw_response: bool = False, **kwargs) -> Union[requests.Response, Dict[str, Any]]:
-        full_url = f"{self.base_url}{endpoint}"
+        full_url = self._build_api_url(endpoint)
         _headers = self.headers.copy()
         if headers:
             _headers.update(headers)
@@ -288,7 +317,7 @@ class APIClient:
     # @THROW: SupersetAPIError, NetworkError, TypeError.
     def upload_file(self, endpoint: str, file_info: Dict[str, Any], extra_data: Optional[Dict] = None, timeout: Optional[int] = None) -> Dict:
         with belief_scope("upload_file"):
-            full_url = f"{self.base_url}{endpoint}"
+            full_url = self._build_api_url(endpoint)
             _headers = self.headers.copy()
             _headers.pop('Content-Type', None)
         

backend/src/dependencies.py

@@ -14,20 +14,21 @@ from .core.config_manager import ConfigManager
 from .core.scheduler import SchedulerService
 from .services.resource_service import ResourceService
 from .services.mapping_service import MappingService
+from .services.clean_release.repository import CleanReleaseRepository
 from .core.database import init_db, get_auth_db
 from .core.logger import logger
 from .core.auth.jwt import decode_token
 from .core.auth.repository import AuthRepository
 from .models.auth import User
 
-# Initialize singletons
-# Use absolute path relative to this file to ensure plugins are found regardless of CWD
-project_root = Path(__file__).parent.parent.parent
-config_path = project_root / "config.json"
-
-# Initialize database before services that use persisted configuration.
-init_db()
-config_manager = ConfigManager(config_path=str(config_path))
+# Initialize singletons
+# Use absolute path relative to this file to ensure plugins are found regardless of CWD
+project_root = Path(__file__).parent.parent.parent
+config_path = project_root / "config.json"
+
+# Initialize database before services that use persisted configuration.
+init_db()
+config_manager = ConfigManager(config_path=str(config_path))
 
 # [DEF:get_config_manager:Function]
 # @PURPOSE: Dependency injector for ConfigManager.
@@ -54,6 +55,9 @@ logger.info("SchedulerService initialized")
 resource_service = ResourceService()
 logger.info("ResourceService initialized")
 
+clean_release_repository = CleanReleaseRepository()
+logger.info("CleanReleaseRepository initialized")
+
 # [DEF:get_plugin_loader:Function]
 # @PURPOSE: Dependency injector for PluginLoader.
 # @PRE: Global plugin_loader must be initialized.
@@ -104,6 +108,16 @@ def get_mapping_service() -> MappingService:
     return MappingService(config_manager)
 # [/DEF:get_mapping_service:Function]
 
+
+# [DEF:get_clean_release_repository:Function]
+# @PURPOSE: Dependency injector for CleanReleaseRepository.
+# @PRE: Global clean_release_repository must be initialized.
+# @POST: Returns shared CleanReleaseRepository instance.
+# @RETURN: CleanReleaseRepository - Shared clean release repository instance.
+def get_clean_release_repository() -> CleanReleaseRepository:
+    return clean_release_repository
+# [/DEF:get_clean_release_repository:Function]
+
 # [DEF:oauth2_scheme:Variable]
 # @PURPOSE: OAuth2 password bearer scheme for token extraction.
 oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/api/auth/login")

backend/src/models/clean_release.py

@@ -0,0 +1,319 @@
+# [DEF:backend.src.models.clean_release:Module]
+# @TIER: CRITICAL
+# @SEMANTICS: clean-release, models, lifecycle, policy, manifest, compliance
+# @PURPOSE: Define clean release domain entities and validation contracts for enterprise compliance flow.
+# @LAYER: Domain
+# @RELATION: BINDS_TO -> specs/023-clean-repo-enterprise/data-model.md
+# @INVARIANT: Enterprise-clean policy always forbids external sources.
+
+from __future__ import annotations
+
+from datetime import datetime
+from enum import Enum
+from typing import List, Optional
+
+from pydantic import BaseModel, Field, model_validator
+
+
+# [DEF:ReleaseCandidateStatus:Class]
+# @PURPOSE: Lifecycle states for release candidate.
+class ReleaseCandidateStatus(str, Enum):
+    DRAFT = "draft"
+    PREPARED = "prepared"
+    COMPLIANT = "compliant"
+    BLOCKED = "blocked"
+    RELEASED = "released"
+# [/DEF:ReleaseCandidateStatus:Class]
+
+
+# [DEF:ProfileType:Class]
+# @PURPOSE: Supported profile identifiers.
+class ProfileType(str, Enum):
+    ENTERPRISE_CLEAN = "enterprise-clean"
+    DEVELOPMENT = "development"
+# [/DEF:ProfileType:Class]
+
+
+# [DEF:ClassificationType:Class]
+# @PURPOSE: Manifest classification outcomes for artifacts.
+class ClassificationType(str, Enum):
+    REQUIRED_SYSTEM = "required-system"
+    ALLOWED = "allowed"
+    EXCLUDED_PROHIBITED = "excluded-prohibited"
+# [/DEF:ClassificationType:Class]
+
+
+# [DEF:RegistryStatus:Class]
+# @PURPOSE: Registry lifecycle status.
+class RegistryStatus(str, Enum):
+    ACTIVE = "active"
+    INACTIVE = "inactive"
+# [/DEF:RegistryStatus:Class]
+
+
+# [DEF:CheckFinalStatus:Class]
+# @PURPOSE: Final status for compliance check run.
+class CheckFinalStatus(str, Enum):
+    RUNNING = "running"
+    COMPLIANT = "compliant"
+    BLOCKED = "blocked"
+    FAILED = "failed"
+# [/DEF:CheckFinalStatus:Class]
+
+
+# [DEF:ExecutionMode:Class]
+# @PURPOSE: Execution channel for compliance checks.
+class ExecutionMode(str, Enum):
+    TUI = "tui"
+    CI = "ci"
+# [/DEF:ExecutionMode:Class]
+
+
+# [DEF:CheckStageName:Class]
+# @PURPOSE: Mandatory check stages.
+class CheckStageName(str, Enum):
+    DATA_PURITY = "data_purity"
+    INTERNAL_SOURCES_ONLY = "internal_sources_only"
+    NO_EXTERNAL_ENDPOINTS = "no_external_endpoints"
+    MANIFEST_CONSISTENCY = "manifest_consistency"
+# [/DEF:CheckStageName:Class]
+
+
+# [DEF:CheckStageStatus:Class]
+# @PURPOSE: Stage-level execution status.
+class CheckStageStatus(str, Enum):
+    PASS = "pass"
+    FAIL = "fail"
+    SKIPPED = "skipped"
+# [/DEF:CheckStageStatus:Class]
+
+
+# [DEF:ViolationCategory:Class]
+# @PURPOSE: Normalized compliance violation categories.
+class ViolationCategory(str, Enum):
+    DATA_PURITY = "data-purity"
+    EXTERNAL_SOURCE = "external-source"
+    MANIFEST_INTEGRITY = "manifest-integrity"
+    POLICY_CONFLICT = "policy-conflict"
+    OPERATIONAL_RISK = "operational-risk"
+# [/DEF:ViolationCategory:Class]
+
+
+# [DEF:ViolationSeverity:Class]
+# @PURPOSE: Severity levels for violation triage.
+class ViolationSeverity(str, Enum):
+    CRITICAL = "critical"
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+# [/DEF:ViolationSeverity:Class]
+
+
+# [DEF:ReleaseCandidate:Class]
+# @PURPOSE: Candidate metadata for clean-release workflow.
+# @PRE: candidate_id, source_snapshot_ref are non-empty.
+# @POST: Model instance is valid for lifecycle transitions.
+class ReleaseCandidate(BaseModel):
+    candidate_id: str
+    version: str
+    profile: ProfileType
+    created_at: datetime
+    created_by: str
+    source_snapshot_ref: str
+    status: ReleaseCandidateStatus = ReleaseCandidateStatus.DRAFT
+
+    @model_validator(mode="after")
+    def _validate_non_empty(self):
+        if not self.candidate_id.strip():
+            raise ValueError("candidate_id must be non-empty")
+        if not self.source_snapshot_ref.strip():
+            raise ValueError("source_snapshot_ref must be non-empty")
+        return self
+# [/DEF:ReleaseCandidate:Class]
+
+
+# [DEF:CleanProfilePolicy:Class]
+# @PURPOSE: Policy contract for artifact/source decisions.
+class CleanProfilePolicy(BaseModel):
+    policy_id: str
+    policy_version: str
+    active: bool
+    prohibited_artifact_categories: List[str] = Field(default_factory=list)
+    required_system_categories: List[str] = Field(default_factory=list)
+    external_source_forbidden: bool = True
+    internal_source_registry_ref: str
+    effective_from: datetime
+    effective_to: Optional[datetime] = None
+    profile: ProfileType = ProfileType.ENTERPRISE_CLEAN
+
+    @model_validator(mode="after")
+    def _validate_policy(self):
+        if self.profile == ProfileType.ENTERPRISE_CLEAN:
+            if not self.external_source_forbidden:
+                raise ValueError("enterprise-clean policy requires external_source_forbidden=true")
+            if not self.prohibited_artifact_categories:
+                raise ValueError("enterprise-clean policy requires prohibited_artifact_categories")
+        if not self.internal_source_registry_ref.strip():
+            raise ValueError("internal_source_registry_ref must be non-empty")
+        return self
+# [/DEF:CleanProfilePolicy:Class]
+
+
+# [DEF:ResourceSourceEntry:Class]
+# @PURPOSE: One internal source definition.
+class ResourceSourceEntry(BaseModel):
+    source_id: str
+    host: str
+    protocol: str
+    purpose: str
+    allowed_paths: List[str] = Field(default_factory=list)
+    enabled: bool = True
+# [/DEF:ResourceSourceEntry:Class]
+
+
+# [DEF:ResourceSourceRegistry:Class]
+# @PURPOSE: Allowlist of internal sources.
+class ResourceSourceRegistry(BaseModel):
+    registry_id: str
+    name: str
+    entries: List[ResourceSourceEntry]
+    updated_at: datetime
+    updated_by: str
+    status: RegistryStatus = RegistryStatus.ACTIVE
+
+    @model_validator(mode="after")
+    def _validate_registry(self):
+        if not self.entries:
+            raise ValueError("registry entries cannot be empty")
+        if self.status == RegistryStatus.ACTIVE and not any(e.enabled for e in self.entries):
+            raise ValueError("active registry must include at least one enabled entry")
+        return self
+# [/DEF:ResourceSourceRegistry:Class]
+
+
+# [DEF:ManifestItem:Class]
+# @PURPOSE: One artifact entry in manifest.
+class ManifestItem(BaseModel):
+    path: str
+    category: str
+    classification: ClassificationType
+    reason: str
+    checksum: Optional[str] = None
+# [/DEF:ManifestItem:Class]
+
+
+# [DEF:ManifestSummary:Class]
+# @PURPOSE: Aggregate counters for manifest decisions.
+class ManifestSummary(BaseModel):
+    included_count: int = Field(ge=0)
+    excluded_count: int = Field(ge=0)
+    prohibited_detected_count: int = Field(ge=0)
+# [/DEF:ManifestSummary:Class]
+
+
+# [DEF:DistributionManifest:Class]
+# @PURPOSE: Deterministic release composition for audit.
+class DistributionManifest(BaseModel):
+    manifest_id: str
+    candidate_id: str
+    policy_id: str
+    generated_at: datetime
+    generated_by: str
+    items: List[ManifestItem]
+    summary: ManifestSummary
+    deterministic_hash: str
+
+    @model_validator(mode="after")
+    def _validate_counts(self):
+        if self.summary.included_count + self.summary.excluded_count != len(self.items):
+            raise ValueError("manifest summary counts must match items size")
+        return self
+# [/DEF:DistributionManifest:Class]
+
+
+# [DEF:CheckStageResult:Class]
+# @PURPOSE: Per-stage compliance result.
+class CheckStageResult(BaseModel):
+    stage: CheckStageName
+    status: CheckStageStatus
+    details: Optional[str] = None
+    duration_ms: Optional[int] = Field(default=None, ge=0)
+# [/DEF:CheckStageResult:Class]
+
+
+# [DEF:ComplianceCheckRun:Class]
+# @PURPOSE: One execution run of compliance pipeline.
+class ComplianceCheckRun(BaseModel):
+    check_run_id: str
+    candidate_id: str
+    policy_id: str
+    started_at: datetime
+    finished_at: Optional[datetime] = None
+    final_status: CheckFinalStatus = CheckFinalStatus.RUNNING
+    triggered_by: str
+    execution_mode: ExecutionMode
+    checks: List[CheckStageResult] = Field(default_factory=list)
+
+    @model_validator(mode="after")
+    def _validate_terminal_integrity(self):
+        if self.final_status == CheckFinalStatus.COMPLIANT:
+            mandatory = {c.stage: c.status for c in self.checks}
+            required = {
+                CheckStageName.DATA_PURITY,
+                CheckStageName.INTERNAL_SOURCES_ONLY,
+                CheckStageName.NO_EXTERNAL_ENDPOINTS,
+                CheckStageName.MANIFEST_CONSISTENCY,
+            }
+            if not required.issubset(mandatory.keys()):
+                raise ValueError("compliant run requires all mandatory stages")
+            if any(mandatory[s] != CheckStageStatus.PASS for s in required):
+                raise ValueError("compliant run requires PASS on all mandatory stages")
+        return self
+# [/DEF:ComplianceCheckRun:Class]
+
+
+# [DEF:ComplianceViolation:Class]
+# @PURPOSE: Normalized violation row for triage and blocking decisions.
+class ComplianceViolation(BaseModel):
+    violation_id: str
+    check_run_id: str
+    category: ViolationCategory
+    severity: ViolationSeverity
+    location: str
+    evidence: Optional[str] = None
+    remediation: str
+    blocked_release: bool
+    detected_at: datetime
+
+    @model_validator(mode="after")
+    def _validate_violation(self):
+        if self.category == ViolationCategory.EXTERNAL_SOURCE and not self.blocked_release:
+            raise ValueError("external-source violation must block release")
+        if self.severity == ViolationSeverity.CRITICAL and not self.remediation.strip():
+            raise ValueError("critical violation requires remediation")
+        return self
+# [/DEF:ComplianceViolation:Class]
+
+
+# [DEF:ComplianceReport:Class]
+# @PURPOSE: Final report payload for operator and audit systems.
+class ComplianceReport(BaseModel):
+    report_id: str
+    check_run_id: str
+    candidate_id: str
+    generated_at: datetime
+    final_status: CheckFinalStatus
+    operator_summary: str
+    structured_payload_ref: str
+    violations_count: int = Field(ge=0)
+    blocking_violations_count: int = Field(ge=0)
+
+    @model_validator(mode="after")
+    def _validate_report_counts(self):
+        if self.blocking_violations_count > self.violations_count:
+            raise ValueError("blocking_violations_count cannot exceed violations_count")
+        if self.final_status == CheckFinalStatus.BLOCKED and self.blocking_violations_count <= 0:
+            raise ValueError("blocked report requires blocking violations")
+        return self
+# [/DEF:ComplianceReport:Class]
+# [/DEF:backend.src.models.clean_release:Module]

backend/src/models/report.py

@@ -47,6 +47,19 @@ class ReportStatus(str, Enum):
 # @INVARIANT: The properties accurately describe error state.
 # @SEMANTICS: error, context, payload
 # @PURPOSE: Error and recovery context for failed/partial reports.
+#
+# @TEST_CONTRACT: ErrorContextModel ->
+# {
+#   required_fields: {
+#       message: str
+#   },
+#   optional_fields: {
+#       code: str,
+#       next_actions: list[str]
+#   }
+# }
+# @TEST_FIXTURE: basic_error -> {"message": "Connection timeout", "code": "ERR_504", "next_actions": ["retry"]}
+# @TEST_EDGE: missing_message -> {"code": "ERR_504"}
 class ErrorContext(BaseModel):
     code: Optional[str] = None
     message: str
@@ -59,6 +72,36 @@ class ErrorContext(BaseModel):
 # @INVARIANT: Must represent canonical task record attributes.
 # @SEMANTICS: report, model, summary
 # @PURPOSE: Canonical normalized report envelope for one task execution.
+#
+# @TEST_CONTRACT: TaskReportModel ->
+# {
+#   required_fields: {
+#       report_id: str,
+#       task_id: str,
+#       task_type: TaskType,
+#       status: ReportStatus,
+#       updated_at: datetime,
+#       summary: str
+#   },
+#   invariants: [
+#       "report_id is a non-empty string",
+#       "task_id is a non-empty string",
+#       "summary is a non-empty string"
+#   ]
+# }
+# @TEST_FIXTURE: valid_task_report ->
+# {
+#   report_id: "rep-123",
+#   task_id: "task-456",
+#   task_type: "migration",
+#   status: "success",
+#   updated_at: "2026-02-26T12:00:00Z",
+#   summary: "Migration completed successfully"
+# }
+# @TEST_EDGE: empty_report_id -> {"report_id": "  ", "task_id": "task-456", "task_type": "migration", "status": "success", "updated_at": "2026-02-26T12:00:00Z", "summary": "Done"}
+# @TEST_EDGE: empty_summary -> {"report_id": "rep-123", "task_id": "task-456", "task_type": "migration", "status": "success", "updated_at": "2026-02-26T12:00:00Z", "summary": ""}
+# @TEST_EDGE: invalid_task_type -> {"report_id": "rep-123", "task_id": "task-456", "task_type": "invalid_type", "status": "success", "updated_at": "2026-02-26T12:00:00Z", "summary": "Done"}
+# @TEST_INVARIANT: non_empty_validators -> verifies: [empty_report_id, empty_summary]
 class TaskReport(BaseModel):
     report_id: str
     task_id: str
@@ -85,6 +128,25 @@ class TaskReport(BaseModel):
 # @INVARIANT: Time and pagination queries are mutually consistent.
 # @SEMANTICS: query, filter, search
 # @PURPOSE: Query object for server-side report filtering, sorting, and pagination.
+#
+# @TEST_CONTRACT: ReportQueryModel ->
+# {
+#   optional_fields: {
+#       page: int, page_size: int, task_types: list[TaskType], statuses: list[ReportStatus],
+#       time_from: datetime, time_to: datetime, search: str, sort_by: str, sort_order: str
+#   },
+#   invariants: [
+#       "page >= 1", "1 <= page_size <= 100",
+#       "sort_by in {'updated_at', 'status', 'task_type'}",
+#       "sort_order in {'asc', 'desc'}",
+#       "time_from <= time_to if both exist"
+#   ]
+# }
+# @TEST_FIXTURE: valid_query -> {"page": 1, "page_size":20, "sort_by": "updated_at", "sort_order": "desc"}
+# @TEST_EDGE: invalid_page_size_large -> {"page_size": 150}
+# @TEST_EDGE: invalid_sort_by -> {"sort_by": "unknown_field"}
+# @TEST_EDGE: invalid_time_range -> {"time_from": "2026-02-26T12:00:00Z", "time_to": "2026-02-25T12:00:00Z"}
+# @TEST_INVARIANT: attribute_constraints_enforced -> verifies: [invalid_page_size_large, invalid_sort_by, invalid_time_range]
 class ReportQuery(BaseModel):
     page: int = Field(default=1, ge=1)
     page_size: int = Field(default=20, ge=1, le=100)
@@ -124,6 +186,16 @@ class ReportQuery(BaseModel):
 # @INVARIANT: Represents paginated data correctly.
 # @SEMANTICS: collection, pagination
 # @PURPOSE: Paginated collection of normalized task reports.
+#
+# @TEST_CONTRACT: ReportCollectionModel ->
+# {
+#   required_fields: {
+#       items: list[TaskReport], total: int, page: int, page_size: int, has_next: bool, applied_filters: ReportQuery
+#   },
+#   invariants: ["total >= 0", "page >= 1", "page_size >= 1"]
+# }
+# @TEST_FIXTURE: empty_collection -> {"items": [], "total": 0, "page": 1, "page_size": 20, "has_next": False, "applied_filters": {}}
+# @TEST_EDGE: negative_total -> {"items": [], "total": -5, "page": 1, "page_size": 20, "has_next": False, "applied_filters": {}}
 class ReportCollection(BaseModel):
     items: List[TaskReport]
     total: int = Field(ge=0)
@@ -139,6 +211,14 @@ class ReportCollection(BaseModel):
 # @INVARIANT: Incorporates a report and logs correctly.
 # @SEMANTICS: view, detail, logs
 # @PURPOSE: Detailed report representation including diagnostics and recovery actions.
+#
+# @TEST_CONTRACT: ReportDetailViewModel ->
+# {
+#   required_fields: {report: TaskReport},
+#   optional_fields: {timeline: list[dict], diagnostics: dict, next_actions: list[str]}
+# }
+# @TEST_FIXTURE: valid_detail -> {"report": {"report_id": "rep-1", "task_id": "task-1", "task_type": "backup", "status": "success", "updated_at": "2026-02-26T12:00:00Z", "summary": "Done"}}
+# @TEST_EDGE: missing_report -> {}
 class ReportDetailView(BaseModel):
     report: TaskReport
     timeline: List[Dict[str, Any]] = Field(default_factory=list)

backend/src/models/task.py

@@ -39,6 +39,61 @@ class TaskRecord(Base):
 # @TIER: CRITICAL
 # @RELATION: DEPENDS_ON -> TaskRecord
 # @INVARIANT: Each log entry belongs to exactly one task.
+#
+# @TEST_CONTRACT: TaskLogCreate ->
+# {
+#   required_fields: {
+#       task_id: str,
+#       timestamp: datetime,
+#       level: str,
+#       source: str,
+#       message: str
+#   },
+#   optional_fields: {
+#       metadata_json: str,
+#       id: int
+#   },
+#   invariants: [
+#       "task_id matches an existing TaskRecord.id"
+#   ]
+# }
+#
+# @TEST_FIXTURE: basic_info_log ->
+# {
+#   task_id: "00000000-0000-0000-0000-000000000000",
+#   timestamp: "2026-02-26T12:00:00Z",
+#   level: "INFO",
+#   source: "system",
+#   message: "Task initialization complete"
+# }
+#
+# @TEST_EDGE: missing_required_field ->
+# {
+#   timestamp: "2026-02-26T12:00:00Z",
+#   level: "ERROR",
+#   source: "system",
+#   message: "Missing task_id"
+# }
+#
+# @TEST_EDGE: invalid_type ->
+# {
+#   task_id: "00000000-0000-0000-0000-000000000000",
+#   timestamp: "2026-02-26T12:00:00Z",
+#   level: 500,
+#   source: "system",
+#   message: "Integer level"
+# }
+#
+# @TEST_EDGE: empty_message ->
+# {
+#   task_id: "00000000-0000-0000-0000-000000000000",
+#   timestamp: "2026-02-26T12:00:00Z",
+#   level: "DEBUG",
+#   source: "system",
+#   message: ""
+# }
+#
+# @TEST_INVARIANT: exact_one_task_association -> verifies: [basic_info_log, missing_required_field]
 class TaskLogRecord(Base):
     __tablename__ = "task_logs"
 

backend/src/scripts/clean_release_tui.py

@@ -0,0 +1,38 @@
+# [DEF:backend.src.scripts.clean_release_tui:Module]
+# @TIER: CRITICAL
+# @SEMANTICS: tui, clean-release, ncurses, operator-flow, placeholder
+# @PURPOSE: Provide clean release TUI entrypoint placeholder for phased implementation.
+# @LAYER: UI
+# @RELATION: BINDS_TO -> specs/023-clean-repo-enterprise/ux_reference.md
+# @INVARIANT: Entry point is executable and does not mutate release data in placeholder mode.
+
+# @PRE: Python runtime is available.
+# @POST: Placeholder message is emitted and process exits with success.
+# @UX_STATE: READY -> Displays profile hints and allowed internal sources
+# @UX_STATE: RUNNING -> Triggered by operator action (F5), check in progress
+# @UX_STATE: BLOCKED -> Violations are displayed with remediation hints
+# @UX_FEEDBACK: Console lines provide immediate operator guidance
+# @UX_RECOVERY: Operator re-runs check after remediation from the same screen
+# @TEST_CONTRACT: TuiEntrypointInput -> ExitCodeInt
+# @TEST_SCENARIO: startup_ready_state -> main prints READY and returns 0
+# @TEST_FIXTURE: tui_placeholder -> INLINE_JSON
+# @TEST_EDGE: stdout_unavailable -> process returns non-zero via runtime exception propagation
+# @TEST_EDGE: interrupted_execution -> user interruption terminates process
+# @TEST_EDGE: invalid_terminal -> fallback text output remains deterministic
+# @TEST_INVARIANT: placeholder_no_mutation -> VERIFIED_BY: [startup_ready_state]
+
+
+def main() -> int:
+    print("Enterprise Clean Release Validator (TUI placeholder)")
+    print("Allowed Internal Sources:")
+    print(" - repo.intra.company.local")
+    print(" - artifacts.intra.company.local")
+    print(" - pypi.intra.company.local")
+    print("Status: READY")
+    print("Use F5 to run check; BLOCKED state will show external-source violation details.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+# [/DEF:backend.src.scripts.clean_release_tui:Module]

backend/src/scripts/dataset_dashboard_analysis.json

@@ -10,7 +10,7 @@
       },
       "changed_by_name": "Superset Admin",
       "changed_on": "2026-02-10T13:39:35.945662",
-      "changed_on_delta_humanized": "15 days ago",
+      "changed_on_delta_humanized": "16 days ago",
       "charts": [
         "TA-0001-001 test_chart"
       ],
@@ -19,7 +19,7 @@
         "id": 1,
         "last_name": "Admin"
       },
-      "created_on_delta_humanized": "15 days ago",
+      "created_on_delta_humanized": "16 days ago",
       "css": null,
       "dashboard_title": "TA-0001 Test dashboard",
       "id": 13,
@@ -54,7 +54,7 @@
         "last_name": "Admin"
       },
       "changed_on": "2026-02-10T13:38:26.175551",
-      "changed_on_humanized": "15 days ago",
+      "changed_on_humanized": "16 days ago",
       "column_formats": {},
       "columns": [
         {
@@ -424,7 +424,7 @@
         "last_name": "Admin"
       },
       "created_on": "2026-02-10T13:38:26.050436",
-      "created_on_humanized": "15 days ago",
+      "created_on_humanized": "16 days ago",
       "database": {
         "allow_multi_catalog": false,
         "backend": "postgresql",

backend/src/services/__tests__/test_resource_service.py

@@ -33,22 +33,43 @@ async def test_get_dashboards_with_status():
         ]
         
         # Mock tasks
-        mock_task = MagicMock()
-        mock_task.id = "task-123"
-        mock_task.status = "SUCCESS"
-        mock_task.params = {"resource_id": "dashboard-1"}
-        mock_task.created_at = datetime.now()
-        
+        task_prod_old = MagicMock()
+        task_prod_old.id = "task-123"
+        task_prod_old.plugin_id = "llm_dashboard_validation"
+        task_prod_old.status = "SUCCESS"
+        task_prod_old.params = {"dashboard_id": "1", "environment_id": "prod"}
+        task_prod_old.started_at = datetime(2024, 1, 1, 10, 0, 0)
+
+        task_prod_new = MagicMock()
+        task_prod_new.id = "task-124"
+        task_prod_new.plugin_id = "llm_dashboard_validation"
+        task_prod_new.status = "TaskStatus.FAILED"
+        task_prod_new.params = {"dashboard_id": "1", "environment_id": "prod"}
+        task_prod_new.result = {"status": "FAIL"}
+        task_prod_new.started_at = datetime(2024, 1, 1, 12, 0, 0)
+
+        task_other_env = MagicMock()
+        task_other_env.id = "task-200"
+        task_other_env.plugin_id = "llm_dashboard_validation"
+        task_other_env.status = "SUCCESS"
+        task_other_env.params = {"dashboard_id": "1", "environment_id": "stage"}
+        task_other_env.started_at = datetime(2024, 1, 1, 13, 0, 0)
+
         env = MagicMock()
         env.id = "prod"
-        
-        result = await service.get_dashboards_with_status(env, [mock_task])
+
+        result = await service.get_dashboards_with_status(
+            env,
+            [task_prod_old, task_prod_new, task_other_env],
+        )
         
         assert len(result) == 2
         assert result[0]["id"] == 1
         assert "git_status" in result[0]
         assert "last_task" in result[0]
-        assert result[0]["last_task"]["task_id"] == "task-123"
+        assert result[0]["last_task"]["task_id"] == "task-124"
+        assert result[0]["last_task"]["status"] == "FAILED"
+        assert result[0]["last_task"]["validation_status"] == "FAIL"
 
 
 # [/DEF:test_get_dashboards_with_status:Function]
@@ -145,7 +166,9 @@ def test_get_git_status_for_dashboard_no_repo():
         
         result = service._get_git_status_for_dashboard(123)
         
-        assert result is None
+        assert result is not None
+        assert result['sync_status'] == 'NO_REPO'
+        assert result['has_repo'] is False
 
 
 # [/DEF:test_get_git_status_for_dashboard_no_repo:Function]
@@ -212,4 +235,38 @@ def test_extract_resource_name_from_task():
 # [/DEF:test_extract_resource_name_from_task:Function]
 
 
-# [/DEF:backend.src.services.__tests__.test_resource_service:Module]
+# [DEF:test_get_last_task_for_resource_empty_tasks:Function]
+# @TEST: _get_last_task_for_resource returns None for empty tasks list
+# @PRE: tasks is empty list
+# @POST: Returns None
+def test_get_last_task_for_resource_empty_tasks():
+    from src.services.resource_service import ResourceService
+    
+    service = ResourceService()
+    
+    result = service._get_last_task_for_resource("dashboard-1", [])
+    assert result is None
+# [/DEF:test_get_last_task_for_resource_empty_tasks:Function]
+
+
+# [DEF:test_get_last_task_for_resource_no_match:Function]
+# @TEST: _get_last_task_for_resource returns None when no tasks match resource_id
+# @PRE: tasks list has no matching resource_id
+# @POST: Returns None
+def test_get_last_task_for_resource_no_match():
+    from src.services.resource_service import ResourceService
+    
+    service = ResourceService()
+    
+    task = MagicMock()
+    task.id = "task-999"
+    task.status = "SUCCESS"
+    task.params = {"resource_id": "dashboard-99"}
+    task.created_at = datetime(2024, 1, 1, 10, 0, 0)
+    
+    result = service._get_last_task_for_resource("dashboard-1", [task])
+    assert result is None
+# [/DEF:test_get_last_task_for_resource_no_match:Function]
+
+
+# [/DEF:backend.src.services.__tests__.test_resource_service:Module]

backend/src/services/clean_release/__init__.py

@@ -0,0 +1,20 @@
+# [DEF:backend.src.services.clean_release:Module]
+# @TIER: STANDARD
+# @SEMANTICS: clean-release, services, package, initialization
+# @PURPOSE: Initialize clean release service package and provide explicit module exports.
+# @LAYER: Domain
+# @RELATION: EXPORTS -> policy_engine, manifest_builder, preparation_service, source_isolation, compliance_orchestrator, report_builder, repository, stages, audit_service
+# @INVARIANT: Package import must not execute runtime side effects beyond symbol export setup.
+
+__all__ = [
+    "policy_engine",
+    "manifest_builder",
+    "preparation_service",
+    "source_isolation",
+    "compliance_orchestrator",
+    "report_builder",
+    "repository",
+    "stages",
+    "audit_service",
+]
+# [/DEF:backend.src.services.clean_release:Module]

backend/src/services/clean_release/__tests__/test_compliance_orchestrator.py

@@ -0,0 +1,85 @@
+# [DEF:backend.tests.services.clean_release.test_compliance_orchestrator:Module]
+# @TIER: STANDARD
+# @SEMANTICS: tests, clean-release, orchestrator, stage-state-machine
+# @PURPOSE: Validate compliance orchestrator stage transitions and final status derivation.
+# @LAYER: Domain
+# @RELATION: TESTS -> backend.src.services.clean_release.compliance_orchestrator
+# @INVARIANT: Failed mandatory stage forces BLOCKED terminal status.
+
+from unittest.mock import patch
+
+import pytest
+
+from src.models.clean_release import (
+    CheckFinalStatus,
+    CheckStageName,
+    CheckStageResult,
+    CheckStageStatus,
+)
+from src.services.clean_release.compliance_orchestrator import CleanComplianceOrchestrator
+from src.services.clean_release.report_builder import ComplianceReportBuilder
+from src.services.clean_release.repository import CleanReleaseRepository
+
+
+# [DEF:test_orchestrator_stage_failure_blocks_release:Function]
+# @PURPOSE: Verify mandatory stage failure forces BLOCKED final status.
+def test_orchestrator_stage_failure_blocks_release():
+    repository = CleanReleaseRepository()
+    orchestrator = CleanComplianceOrchestrator(repository)
+
+    run = orchestrator.start_check_run(
+        candidate_id="2026.03.03-rc1",
+        policy_id="policy-enterprise-clean-v1",
+        triggered_by="tester",
+        execution_mode="tui",
+    )
+    run = orchestrator.execute_stages(
+        run,
+        forced_results=[
+            CheckStageResult(stage=CheckStageName.DATA_PURITY, status=CheckStageStatus.PASS, details="ok"),
+            CheckStageResult(stage=CheckStageName.INTERNAL_SOURCES_ONLY, status=CheckStageStatus.PASS, details="ok"),
+            CheckStageResult(stage=CheckStageName.NO_EXTERNAL_ENDPOINTS, status=CheckStageStatus.FAIL, details="external"),
+            CheckStageResult(stage=CheckStageName.MANIFEST_CONSISTENCY, status=CheckStageStatus.PASS, details="ok"),
+        ],
+    )
+    run = orchestrator.finalize_run(run)
+
+    assert run.final_status == CheckFinalStatus.BLOCKED
+# [/DEF:test_orchestrator_stage_failure_blocks_release:Function]
+
+
+# [DEF:test_orchestrator_missing_stage_result:Function]
+# @PURPOSE: Verify incomplete mandatory stage set cannot end as COMPLIANT and results in FAILED.
+def test_orchestrator_missing_stage_result():
+    repository = CleanReleaseRepository()
+    orchestrator = CleanComplianceOrchestrator(repository)
+
+    run = orchestrator.start_check_run("cand-1", "pol-1", "tester", "tui")
+    run = orchestrator.execute_stages(
+        run,
+        forced_results=[CheckStageResult(stage=CheckStageName.DATA_PURITY, status=CheckStageStatus.PASS, details="ok")],
+    )
+    run = orchestrator.finalize_run(run)
+
+    assert run.final_status == CheckFinalStatus.FAILED
+# [/DEF:test_orchestrator_missing_stage_result:Function]
+
+
+# [DEF:test_orchestrator_report_generation_error:Function]
+# @PURPOSE: Verify downstream report errors do not mutate orchestrator final status.
+def test_orchestrator_report_generation_error():
+    repository = CleanReleaseRepository()
+    orchestrator = CleanComplianceOrchestrator(repository)
+
+    run = orchestrator.start_check_run("cand-1", "pol-1", "tester", "tui")
+    run = orchestrator.finalize_run(run)
+    assert run.final_status == CheckFinalStatus.FAILED
+
+    with patch.object(ComplianceReportBuilder, "build_report_payload", side_effect=ValueError("Report error")):
+        builder = ComplianceReportBuilder(repository)
+        with pytest.raises(ValueError, match="Report error"):
+            builder.build_report_payload(run, [])
+
+    assert run.final_status == CheckFinalStatus.FAILED
+# [/DEF:test_orchestrator_report_generation_error:Function]
+# [/DEF:backend.tests.services.clean_release.test_compliance_orchestrator:Module]

backend/src/services/clean_release/__tests__/test_report_builder.py

@@ -0,0 +1,92 @@
+# [DEF:backend.tests.services.clean_release.test_report_builder:Module]
+# @TIER: STANDARD
+# @SEMANTICS: tests, clean-release, report-builder, counters
+# @PURPOSE: Validate compliance report builder counter integrity and blocked-run constraints.
+# @LAYER: Domain
+# @RELATION: TESTS -> backend.src.services.clean_release.report_builder
+# @INVARIANT: blocked run requires at least one blocking violation.
+
+from datetime import datetime, timezone
+
+import pytest
+
+from src.models.clean_release import (
+    CheckFinalStatus,
+    ComplianceCheckRun,
+    ComplianceViolation,
+    ExecutionMode,
+    ViolationCategory,
+    ViolationSeverity,
+)
+from src.services.clean_release.report_builder import ComplianceReportBuilder
+from src.services.clean_release.repository import CleanReleaseRepository
+
+
+# [DEF:_terminal_run:Function]
+# @PURPOSE: Build terminal/non-terminal run fixtures for report builder tests.
+def _terminal_run(status: CheckFinalStatus) -> ComplianceCheckRun:
+    return ComplianceCheckRun(
+        check_run_id="check-1",
+        candidate_id="2026.03.03-rc1",
+        policy_id="policy-enterprise-clean-v1",
+        started_at=datetime.now(timezone.utc),
+        finished_at=datetime.now(timezone.utc),
+        final_status=status,
+        triggered_by="tester",
+        execution_mode=ExecutionMode.TUI,
+        checks=[],
+    )
+# [/DEF:_terminal_run:Function]
+
+
+# [DEF:_blocking_violation:Function]
+# @PURPOSE: Build a blocking violation fixture for blocked report scenarios.
+def _blocking_violation() -> ComplianceViolation:
+    return ComplianceViolation(
+        violation_id="viol-1",
+        check_run_id="check-1",
+        category=ViolationCategory.EXTERNAL_SOURCE,
+        severity=ViolationSeverity.CRITICAL,
+        location="pypi.org",
+        remediation="replace",
+        blocked_release=True,
+        detected_at=datetime.now(timezone.utc),
+    )
+# [/DEF:_blocking_violation:Function]
+
+
+# [DEF:test_report_builder_blocked_requires_blocking_violations:Function]
+# @PURPOSE: Verify BLOCKED run requires at least one blocking violation.
+def test_report_builder_blocked_requires_blocking_violations():
+    builder = ComplianceReportBuilder(CleanReleaseRepository())
+    run = _terminal_run(CheckFinalStatus.BLOCKED)
+
+    with pytest.raises(ValueError):
+        builder.build_report_payload(run, [])
+# [/DEF:test_report_builder_blocked_requires_blocking_violations:Function]
+
+
+# [DEF:test_report_builder_counter_consistency:Function]
+# @PURPOSE: Verify violations counters remain consistent for blocking payload.
+def test_report_builder_counter_consistency():
+    builder = ComplianceReportBuilder(CleanReleaseRepository())
+    run = _terminal_run(CheckFinalStatus.BLOCKED)
+    report = builder.build_report_payload(run, [_blocking_violation()])
+
+    assert report.violations_count == 1
+    assert report.blocking_violations_count == 1
+# [/DEF:test_report_builder_counter_consistency:Function]
+
+
+# [DEF:test_missing_operator_summary:Function]
+# @PURPOSE: Validate non-terminal run prevents operator summary/report generation.
+def test_missing_operator_summary():
+    builder = ComplianceReportBuilder(CleanReleaseRepository())
+    run = _terminal_run(CheckFinalStatus.RUNNING)
+
+    with pytest.raises(ValueError) as exc:
+        builder.build_report_payload(run, [])
+
+    assert "Cannot build report for non-terminal run" in str(exc.value)
+# [/DEF:test_missing_operator_summary:Function]
+# [/DEF:backend.tests.services.clean_release.test_report_builder:Module]

backend/src/services/clean_release/audit_service.py

@@ -0,0 +1,24 @@
+# [DEF:backend.src.services.clean_release.audit_service:Module]
+# @TIER: STANDARD
+# @SEMANTICS: clean-release, audit, lifecycle, logging
+# @PURPOSE: Provide lightweight audit hooks for clean release preparation/check/report lifecycle.
+# @LAYER: Infra
+# @RELATION: DEPENDS_ON -> backend.src.core.logger
+# @INVARIANT: Audit hooks are append-only log actions.
+
+from __future__ import annotations
+
+from ...core.logger import logger
+
+
+def audit_preparation(candidate_id: str, status: str) -> None:
+    logger.info(f"[REASON] clean-release preparation candidate={candidate_id} status={status}")
+
+
+def audit_check_run(check_run_id: str, final_status: str) -> None:
+    logger.info(f"[REFLECT] clean-release check_run={check_run_id} final_status={final_status}")
+
+
+def audit_report(report_id: str, candidate_id: str) -> None:
+    logger.info(f"[EXPLORE] clean-release report_id={report_id} candidate={candidate_id}")
+# [/DEF:backend.src.services.clean_release.audit_service:Module]

backend/src/services/clean_release/compliance_orchestrator.py

@@ -0,0 +1,66 @@
+# [DEF:backend.src.services.clean_release.compliance_orchestrator:Module]
+# @TIER: CRITICAL
+# @SEMANTICS: clean-release, orchestrator, compliance-gate, stages
+# @PURPOSE: Execute mandatory clean compliance stages and produce final COMPLIANT/BLOCKED/FAILED outcome.
+# @LAYER: Domain
+# @RELATION: DEPENDS_ON -> backend.src.services.clean_release.stages
+# @RELATION: DEPENDS_ON -> backend.src.services.clean_release.report_builder
+# @RELATION: DEPENDS_ON -> backend.src.services.clean_release.repository
+# @INVARIANT: COMPLIANT is impossible when any mandatory stage fails.
+# @TEST_CONTRACT: ComplianceCheckRun -> ComplianceCheckRun
+# @TEST_FIXTURE: compliant_candidate -> file:backend/tests/fixtures/clean_release/fixtures_clean_release.json
+# @TEST_EDGE: stage_failure_blocks_release -> Mandatory stage returns FAIL and final status becomes BLOCKED
+# @TEST_EDGE: missing_stage_result -> Finalization with incomplete/empty mandatory stage set must not produce COMPLIANT
+# @TEST_EDGE: report_generation_error -> Downstream reporting failure does not alter orchestrator status derivation contract
+# @TEST_INVARIANT: compliant_requires_all_mandatory_pass -> VERIFIED_BY: [stage_failure_blocks_release]
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import List, Optional
+from uuid import uuid4
+
+from ...models.clean_release import (
+    CheckFinalStatus,
+    CheckStageName,
+    CheckStageResult,
+    CheckStageStatus,
+    ComplianceCheckRun,
+)
+from .repository import CleanReleaseRepository
+from .stages import MANDATORY_STAGE_ORDER, derive_final_status
+
+
+class CleanComplianceOrchestrator:
+    def __init__(self, repository: CleanReleaseRepository):
+        self.repository = repository
+
+    def start_check_run(self, candidate_id: str, policy_id: str, triggered_by: str, execution_mode: str) -> ComplianceCheckRun:
+        check_run = ComplianceCheckRun(
+            check_run_id=f"check-{uuid4()}",
+            candidate_id=candidate_id,
+            policy_id=policy_id,
+            started_at=datetime.now(timezone.utc),
+            final_status=CheckFinalStatus.RUNNING,
+            triggered_by=triggered_by,
+            execution_mode=execution_mode,
+            checks=[],
+        )
+        return self.repository.save_check_run(check_run)
+
+    def execute_stages(self, check_run: ComplianceCheckRun, forced_results: Optional[List[CheckStageResult]] = None) -> ComplianceCheckRun:
+        if forced_results is not None:
+            check_run.checks = forced_results
+        else:
+            check_run.checks = [
+                CheckStageResult(stage=stage, status=CheckStageStatus.PASS, details="auto-pass")
+                for stage in MANDATORY_STAGE_ORDER
+            ]
+        return self.repository.save_check_run(check_run)
+
+    def finalize_run(self, check_run: ComplianceCheckRun) -> ComplianceCheckRun:
+        final_status = derive_final_status(check_run.checks)
+        check_run.final_status = final_status
+        check_run.finished_at = datetime.now(timezone.utc)
+        return self.repository.save_check_run(check_run)
+# [/DEF:backend.src.services.clean_release.compliance_orchestrator:Module]

backend/src/services/clean_release/manifest_builder.py

@@ -0,0 +1,89 @@
+# [DEF:backend.src.services.clean_release.manifest_builder:Module]
+# @TIER: STANDARD
+# @SEMANTICS: clean-release, manifest, deterministic-hash, summary
+# @PURPOSE: Build deterministic distribution manifest from classified artifact input.
+# @LAYER: Domain
+# @RELATION: DEPENDS_ON -> backend.src.models.clean_release
+# @INVARIANT: Equal semantic artifact sets produce identical deterministic hash values.
+
+from __future__ import annotations
+
+import hashlib
+import json
+from datetime import datetime, timezone
+from typing import Iterable, List, Dict, Any
+
+from ...models.clean_release import (
+    ClassificationType,
+    DistributionManifest,
+    ManifestItem,
+    ManifestSummary,
+)
+
+
+def _stable_hash_payload(candidate_id: str, policy_id: str, items: List[ManifestItem]) -> str:
+    serialized = [
+        {
+            "path": item.path,
+            "category": item.category,
+            "classification": item.classification.value,
+            "reason": item.reason,
+            "checksum": item.checksum,
+        }
+        for item in sorted(items, key=lambda i: (i.path, i.category, i.classification.value, i.reason, i.checksum or ""))
+    ]
+    payload = {
+        "candidate_id": candidate_id,
+        "policy_id": policy_id,
+        "items": serialized,
+    }
+    digest = hashlib.sha256(json.dumps(payload, ensure_ascii=False, sort_keys=True).encode("utf-8")).hexdigest()
+    return digest
+
+
+# [DEF:build_distribution_manifest:Function]
+# @PURPOSE: Build DistributionManifest with deterministic hash and validated counters.
+# @PRE: artifacts list contains normalized classification values.
+# @POST: Returns DistributionManifest with summary counts matching items cardinality.
+def build_distribution_manifest(
+    manifest_id: str,
+    candidate_id: str,
+    policy_id: str,
+    generated_by: str,
+    artifacts: Iterable[Dict[str, Any]],
+) -> DistributionManifest:
+    items = [
+        ManifestItem(
+            path=a["path"],
+            category=a["category"],
+            classification=ClassificationType(a["classification"]),
+            reason=a["reason"],
+            checksum=a.get("checksum"),
+        )
+        for a in artifacts
+    ]
+
+    included_count = sum(1 for item in items if item.classification in {ClassificationType.REQUIRED_SYSTEM, ClassificationType.ALLOWED})
+    excluded_count = sum(1 for item in items if item.classification == ClassificationType.EXCLUDED_PROHIBITED)
+    prohibited_detected_count = excluded_count
+
+    summary = ManifestSummary(
+        included_count=included_count,
+        excluded_count=excluded_count,
+        prohibited_detected_count=prohibited_detected_count,
+    )
+
+    deterministic_hash = _stable_hash_payload(candidate_id, policy_id, items)
+
+    return DistributionManifest(
+        manifest_id=manifest_id,
+        candidate_id=candidate_id,
+        policy_id=policy_id,
+        generated_at=datetime.now(timezone.utc),
+        generated_by=generated_by,
+        items=items,
+        summary=summary,
+        deterministic_hash=deterministic_hash,
+    )
+# [/DEF:build_distribution_manifest:Function]
+# [/DEF:backend.src.services.clean_release.manifest_builder:Module]

backend/src/services/clean_release/policy_engine.py

@@ -0,0 +1,141 @@
+# [DEF:backend.src.services.clean_release.policy_engine:Module]
+# @TIER: CRITICAL
+# @SEMANTICS: clean-release, policy, classification, source-isolation
+# @PURPOSE: Evaluate artifact/source policies for enterprise clean profile with deterministic outcomes.
+# @LAYER: Domain
+# @RELATION: DEPENDS_ON -> backend.src.models.clean_release.CleanProfilePolicy
+# @RELATION: DEPENDS_ON -> backend.src.models.clean_release.ResourceSourceRegistry
+# @INVARIANT: Enterprise-clean policy always treats non-registry sources as violations.
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Dict, Iterable, List, Tuple
+
+from ...core.logger import belief_scope, logger
+from ...models.clean_release import CleanProfilePolicy, ResourceSourceRegistry
+
+
+@dataclass
+class PolicyValidationResult:
+    ok: bool
+    blocking_reasons: List[str]
+
+
+@dataclass
+class SourceValidationResult:
+    ok: bool
+    violation: Dict | None
+
+
+# [DEF:CleanPolicyEngine:Class]
+# @PRE: Active policy exists and is internally consistent.
+# @POST: Deterministic classification and source validation are available.
+# @TEST_CONTRACT: CandidateEvaluationInput -> PolicyValidationResult|SourceValidationResult
+# @TEST_SCENARIO: policy_valid -> Enterprise clean policy with matching registry returns ok=True
+# @TEST_FIXTURE: policy_enterprise_clean -> file:backend/tests/fixtures/clean_release/fixtures_clean_release.json
+# @TEST_EDGE: missing_registry_ref -> policy has empty internal_source_registry_ref
+# @TEST_EDGE: conflicting_registry -> policy registry ref does not match registry id
+# @TEST_EDGE: external_endpoint -> endpoint not present in enabled internal registry entries
+# @TEST_INVARIANT: deterministic_classification -> VERIFIED_BY: [policy_valid]
+class CleanPolicyEngine:
+    def __init__(self, policy: CleanProfilePolicy, registry: ResourceSourceRegistry):
+        self.policy = policy
+        self.registry = registry
+
+    def validate_policy(self) -> PolicyValidationResult:
+        with belief_scope("clean_policy_engine.validate_policy"):
+            logger.reason("Validating enterprise-clean policy and internal registry consistency")
+            reasons: List[str] = []
+
+            if not self.policy.active:
+                reasons.append("Policy must be active")
+            if not self.policy.internal_source_registry_ref.strip():
+                reasons.append("Policy missing internal_source_registry_ref")
+            if self.policy.profile.value == "enterprise-clean" and not self.policy.prohibited_artifact_categories:
+                reasons.append("Enterprise policy requires prohibited artifact categories")
+            if self.policy.profile.value == "enterprise-clean" and not self.policy.external_source_forbidden:
+                reasons.append("Enterprise policy requires external_source_forbidden=true")
+            if self.registry.registry_id != self.policy.internal_source_registry_ref:
+                reasons.append("Policy registry ref does not match provided registry")
+            if not self.registry.entries:
+                reasons.append("Registry must contain entries")
+
+            logger.reflect(f"Policy validation completed. blocking_reasons={len(reasons)}")
+            return PolicyValidationResult(ok=len(reasons) == 0, blocking_reasons=reasons)
+
+    def classify_artifact(self, artifact: Dict) -> str:
+        category = (artifact.get("category") or "").strip()
+        if category in self.policy.required_system_categories:
+            logger.reason(f"Artifact category '{category}' classified as required-system")
+            return "required-system"
+        if category in self.policy.prohibited_artifact_categories:
+            logger.reason(f"Artifact category '{category}' classified as excluded-prohibited")
+            return "excluded-prohibited"
+        logger.reflect(f"Artifact category '{category}' classified as allowed")
+        return "allowed"
+
+    def validate_resource_source(self, endpoint: str) -> SourceValidationResult:
+        with belief_scope("clean_policy_engine.validate_resource_source"):
+            if not endpoint:
+                logger.explore("Empty endpoint detected; treating as blocking external-source violation")
+                return SourceValidationResult(
+                    ok=False,
+                    violation={
+                        "category": "external-source",
+                        "location": "<empty-endpoint>",
+                        "remediation": "Replace with approved internal server",
+                        "blocked_release": True,
+                    },
+                )
+
+            allowed_hosts = {entry.host for entry in self.registry.entries if entry.enabled}
+            normalized = endpoint.strip().lower()
+
+            if normalized in allowed_hosts:
+                logger.reason(f"Endpoint '{normalized}' is present in internal allowlist")
+                return SourceValidationResult(ok=True, violation=None)
+
+            logger.explore(f"Endpoint '{endpoint}' is outside internal allowlist")
+            return SourceValidationResult(
+                ok=False,
+                violation={
+                    "category": "external-source",
+                    "location": endpoint,
+                    "remediation": "Replace with approved internal server",
+                    "blocked_release": True,
+                },
+            )
+
+    def evaluate_candidate(self, artifacts: Iterable[Dict], sources: Iterable[str]) -> Tuple[List[Dict], List[Dict]]:
+        with belief_scope("clean_policy_engine.evaluate_candidate"):
+            logger.reason("Evaluating candidate artifacts and resource sources against enterprise policy")
+            classified: List[Dict] = []
+            violations: List[Dict] = []
+
+            for artifact in artifacts:
+                classification = self.classify_artifact(artifact)
+                enriched = dict(artifact)
+                enriched["classification"] = classification
+                if classification == "excluded-prohibited":
+                    violations.append(
+                        {
+                            "category": "data-purity",
+                            "location": artifact.get("path", "<unknown-path>"),
+                            "remediation": "Remove prohibited content",
+                            "blocked_release": True,
+                        }
+                    )
+                classified.append(enriched)
+
+            for source in sources:
+                source_result = self.validate_resource_source(source)
+                if not source_result.ok and source_result.violation:
+                    violations.append(source_result.violation)
+
+            logger.reflect(
+                f"Candidate evaluation finished. artifacts={len(classified)} violations={len(violations)}"
+            )
+            return classified, violations
+# [/DEF:CleanPolicyEngine:Class]
+# [/DEF:backend.src.services.clean_release.policy_engine:Module]

backend/src/services/clean_release/preparation_service.py

@@ -0,0 +1,67 @@
+# [DEF:backend.src.services.clean_release.preparation_service:Module]
+# @TIER: STANDARD
+# @SEMANTICS: clean-release, preparation, manifest, policy-evaluation
+# @PURPOSE: Prepare release candidate by policy evaluation and deterministic manifest creation.
+# @LAYER: Domain
+# @RELATION: DEPENDS_ON -> backend.src.services.clean_release.policy_engine
+# @RELATION: DEPENDS_ON -> backend.src.services.clean_release.manifest_builder
+# @RELATION: DEPENDS_ON -> backend.src.services.clean_release.repository
+# @INVARIANT: Candidate preparation always persists manifest and candidate status deterministically.
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Dict, Iterable
+
+from .manifest_builder import build_distribution_manifest
+from .policy_engine import CleanPolicyEngine
+from .repository import CleanReleaseRepository
+from ...models.clean_release import ReleaseCandidateStatus
+
+
+def prepare_candidate(
+    repository: CleanReleaseRepository,
+    candidate_id: str,
+    artifacts: Iterable[Dict],
+    sources: Iterable[str],
+    operator_id: str,
+) -> Dict:
+    candidate = repository.get_candidate(candidate_id)
+    if candidate is None:
+        raise ValueError(f"Candidate not found: {candidate_id}")
+
+    policy = repository.get_active_policy()
+    if policy is None:
+        raise ValueError("Active clean policy not found")
+
+    registry = repository.get_registry(policy.internal_source_registry_ref)
+    if registry is None:
+        raise ValueError("Registry not found for active policy")
+
+    engine = CleanPolicyEngine(policy=policy, registry=registry)
+    validation = engine.validate_policy()
+    if not validation.ok:
+        raise ValueError(f"Invalid policy: {validation.blocking_reasons}")
+
+    classified, violations = engine.evaluate_candidate(artifacts=artifacts, sources=sources)
+
+    manifest = build_distribution_manifest(
+        manifest_id=f"manifest-{candidate_id}",
+        candidate_id=candidate_id,
+        policy_id=policy.policy_id,
+        generated_by=operator_id,
+        artifacts=classified,
+    )
+    repository.save_manifest(manifest)
+
+    candidate.status = ReleaseCandidateStatus.BLOCKED if violations else ReleaseCandidateStatus.PREPARED
+    repository.save_candidate(candidate)
+
+    return {
+        "candidate_id": candidate_id,
+        "status": candidate.status.value,
+        "manifest_id": manifest.manifest_id,
+        "violations": violations,
+        "prepared_at": datetime.now(timezone.utc).isoformat(),
+    }
+# [/DEF:backend.src.services.clean_release.preparation_service:Module]

backend/src/services/clean_release/report_builder.py

@@ -0,0 +1,60 @@
+# [DEF:backend.src.services.clean_release.report_builder:Module]
+# @TIER: CRITICAL
+# @SEMANTICS: clean-release, report, audit, counters, violations
+# @PURPOSE: Build and persist compliance reports with consistent counter invariants.
+# @LAYER: Domain
+# @RELATION: DEPENDS_ON -> backend.src.models.clean_release
+# @RELATION: DEPENDS_ON -> backend.src.services.clean_release.repository
+# @INVARIANT: blocking_violations_count never exceeds violations_count.
+# @TEST_CONTRACT: ComplianceCheckRun,List[ComplianceViolation] -> ComplianceReport
+# @TEST_FIXTURE: blocked_with_two_violations -> file:backend/tests/fixtures/clean_release/fixtures_clean_release.json
+# @TEST_EDGE: empty_violations_for_blocked -> BLOCKED run with zero blocking violations raises ValueError
+# @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]
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from uuid import uuid4
+from typing import List
+
+from ...models.clean_release import CheckFinalStatus, ComplianceCheckRun, ComplianceReport, ComplianceViolation
+from .repository import CleanReleaseRepository
+
+
+class ComplianceReportBuilder:
+    def __init__(self, repository: CleanReleaseRepository):
+        self.repository = repository
+
+    def build_report_payload(self, check_run: ComplianceCheckRun, violations: List[ComplianceViolation]) -> ComplianceReport:
+        if check_run.final_status == CheckFinalStatus.RUNNING:
+            raise ValueError("Cannot build report for non-terminal run")
+
+        violations_count = len(violations)
+        blocking_violations_count = sum(1 for v in violations if v.blocked_release)
+
+        if check_run.final_status == CheckFinalStatus.BLOCKED and blocking_violations_count <= 0:
+            raise ValueError("Blocked run requires at least one blocking violation")
+
+        summary = (
+            "Compliance passed with no blocking violations"
+            if check_run.final_status == CheckFinalStatus.COMPLIANT
+            else f"Blocked with {blocking_violations_count} blocking violation(s)"
+        )
+
+        return ComplianceReport(
+            report_id=f"CCR-{uuid4()}",
+            check_run_id=check_run.check_run_id,
+            candidate_id=check_run.candidate_id,
+            generated_at=datetime.now(timezone.utc),
+            final_status=check_run.final_status,
+            operator_summary=summary,
+            structured_payload_ref=f"inmemory://check-runs/{check_run.check_run_id}/report",
+            violations_count=violations_count,
+            blocking_violations_count=blocking_violations_count,
+        )
+
+    def persist_report(self, report: ComplianceReport) -> ComplianceReport:
+        return self.repository.save_report(report)
+# [/DEF:backend.src.services.clean_release.report_builder:Module]

backend/src/services/clean_release/repository.py

@@ -0,0 +1,89 @@
+# [DEF:backend.src.services.clean_release.repository:Module]
+# @TIER: STANDARD
+# @SEMANTICS: clean-release, repository, persistence, in-memory
+# @PURPOSE: Provide repository adapter for clean release entities with deterministic access methods.
+# @LAYER: Infra
+# @RELATION: DEPENDS_ON -> backend.src.models.clean_release
+# @INVARIANT: Repository operations are side-effect free outside explicit save/update calls.
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional
+
+from ...models.clean_release import (
+    CleanProfilePolicy,
+    ComplianceCheckRun,
+    ComplianceReport,
+    ComplianceViolation,
+    DistributionManifest,
+    ReleaseCandidate,
+    ResourceSourceRegistry,
+)
+
+
+@dataclass
+class CleanReleaseRepository:
+    candidates: Dict[str, ReleaseCandidate] = field(default_factory=dict)
+    policies: Dict[str, CleanProfilePolicy] = field(default_factory=dict)
+    registries: Dict[str, ResourceSourceRegistry] = field(default_factory=dict)
+    manifests: Dict[str, DistributionManifest] = field(default_factory=dict)
+    check_runs: Dict[str, ComplianceCheckRun] = field(default_factory=dict)
+    reports: Dict[str, ComplianceReport] = field(default_factory=dict)
+    violations: Dict[str, ComplianceViolation] = field(default_factory=dict)
+
+    def save_candidate(self, candidate: ReleaseCandidate) -> ReleaseCandidate:
+        self.candidates[candidate.candidate_id] = candidate
+        return candidate
+
+    def get_candidate(self, candidate_id: str) -> Optional[ReleaseCandidate]:
+        return self.candidates.get(candidate_id)
+
+    def save_policy(self, policy: CleanProfilePolicy) -> CleanProfilePolicy:
+        self.policies[policy.policy_id] = policy
+        return policy
+
+    def get_policy(self, policy_id: str) -> Optional[CleanProfilePolicy]:
+        return self.policies.get(policy_id)
+
+    def get_active_policy(self) -> Optional[CleanProfilePolicy]:
+        for policy in self.policies.values():
+            if policy.active:
+                return policy
+        return None
+
+    def save_registry(self, registry: ResourceSourceRegistry) -> ResourceSourceRegistry:
+        self.registries[registry.registry_id] = registry
+        return registry
+
+    def get_registry(self, registry_id: str) -> Optional[ResourceSourceRegistry]:
+        return self.registries.get(registry_id)
+
+    def save_manifest(self, manifest: DistributionManifest) -> DistributionManifest:
+        self.manifests[manifest.manifest_id] = manifest
+        return manifest
+
+    def get_manifest(self, manifest_id: str) -> Optional[DistributionManifest]:
+        return self.manifests.get(manifest_id)
+
+    def save_check_run(self, check_run: ComplianceCheckRun) -> ComplianceCheckRun:
+        self.check_runs[check_run.check_run_id] = check_run
+        return check_run
+
+    def get_check_run(self, check_run_id: str) -> Optional[ComplianceCheckRun]:
+        return self.check_runs.get(check_run_id)
+
+    def save_report(self, report: ComplianceReport) -> ComplianceReport:
+        self.reports[report.report_id] = report
+        return report
+
+    def get_report(self, report_id: str) -> Optional[ComplianceReport]:
+        return self.reports.get(report_id)
+
+    def save_violation(self, violation: ComplianceViolation) -> ComplianceViolation:
+        self.violations[violation.violation_id] = violation
+        return violation
+
+    def get_violations_by_check_run(self, check_run_id: str) -> List[ComplianceViolation]:
+        return [v for v in self.violations.values() if v.check_run_id == check_run_id]
+# [/DEF:backend.src.services.clean_release.repository:Module]

backend/src/services/clean_release/source_isolation.py

@@ -0,0 +1,33 @@
+# [DEF:backend.src.services.clean_release.source_isolation:Module]
+# @TIER: STANDARD
+# @SEMANTICS: clean-release, source-isolation, internal-only, validation
+# @PURPOSE: Validate that all resource endpoints belong to the approved internal source registry.
+# @LAYER: Domain
+# @RELATION: DEPENDS_ON -> backend.src.models.clean_release.ResourceSourceRegistry
+# @INVARIANT: Any endpoint outside enabled registry entries is treated as external-source violation.
+
+from __future__ import annotations
+
+from typing import Dict, Iterable, List
+
+from ...models.clean_release import ResourceSourceRegistry
+
+
+def validate_internal_sources(registry: ResourceSourceRegistry, endpoints: Iterable[str]) -> Dict:
+    allowed_hosts = {entry.host.strip().lower() for entry in registry.entries if entry.enabled}
+    violations: List[Dict] = []
+
+    for endpoint in endpoints:
+        normalized = (endpoint or "").strip().lower()
+        if not normalized or normalized not in allowed_hosts:
+            violations.append(
+                {
+                    "category": "external-source",
+                    "location": endpoint or "<empty-endpoint>",
+                    "remediation": "Replace with approved internal server",
+                    "blocked_release": True,
+                }
+            )
+
+    return {"ok": len(violations) == 0, "violations": violations}
+# [/DEF:backend.src.services.clean_release.source_isolation:Module]

backend/src/services/clean_release/stages.py

@@ -0,0 +1,59 @@
+# [DEF:backend.src.services.clean_release.stages:Module]
+# @TIER: STANDARD
+# @SEMANTICS: clean-release, compliance, stages, state-machine
+# @PURPOSE: Define compliance stage order and helper functions for deterministic run-state evaluation.
+# @LAYER: Domain
+# @RELATION: DEPENDS_ON -> backend.src.models.clean_release
+# @INVARIANT: Stage order remains deterministic for all compliance runs.
+
+from __future__ import annotations
+
+from typing import Dict, Iterable, List
+
+from ...models.clean_release import CheckFinalStatus, CheckStageName, CheckStageResult, CheckStageStatus
+
+MANDATORY_STAGE_ORDER: List[CheckStageName] = [
+    CheckStageName.DATA_PURITY,
+    CheckStageName.INTERNAL_SOURCES_ONLY,
+    CheckStageName.NO_EXTERNAL_ENDPOINTS,
+    CheckStageName.MANIFEST_CONSISTENCY,
+]
+
+
+# [DEF:stage_result_map:Function]
+# @PURPOSE: Convert stage result list to dictionary by stage name.
+# @PRE: stage_results may be empty or contain unique stage names.
+# @POST: Returns stage->status dictionary for downstream evaluation.
+def stage_result_map(stage_results: Iterable[CheckStageResult]) -> Dict[CheckStageName, CheckStageStatus]:
+    return {result.stage: result.status for result in stage_results}
+# [/DEF:stage_result_map:Function]
+
+
+# [DEF:missing_mandatory_stages:Function]
+# @PURPOSE: Identify mandatory stages that are absent from run results.
+# @PRE: stage_status_map contains zero or more known stage statuses.
+# @POST: Returns ordered list of missing mandatory stages.
+def missing_mandatory_stages(stage_status_map: Dict[CheckStageName, CheckStageStatus]) -> List[CheckStageName]:
+    return [stage for stage in MANDATORY_STAGE_ORDER if stage not in stage_status_map]
+# [/DEF:missing_mandatory_stages:Function]
+
+
+# [DEF:derive_final_status:Function]
+# @PURPOSE: Derive final run status from stage results with deterministic blocking behavior.
+# @PRE: Stage statuses correspond to compliance checks.
+# @POST: Returns one of COMPLIANT/BLOCKED/FAILED according to mandatory stage outcomes.
+def derive_final_status(stage_results: Iterable[CheckStageResult]) -> CheckFinalStatus:
+    status_map = stage_result_map(stage_results)
+    missing = missing_mandatory_stages(status_map)
+    if missing:
+        return CheckFinalStatus.FAILED
+
+    for stage in MANDATORY_STAGE_ORDER:
+        if status_map.get(stage) == CheckStageStatus.FAIL:
+            return CheckFinalStatus.BLOCKED
+        if status_map.get(stage) == CheckStageStatus.SKIPPED:
+            return CheckFinalStatus.FAILED
+
+    return CheckFinalStatus.COMPLIANT
+# [/DEF:derive_final_status:Function]
+# [/DEF:backend.src.services.clean_release.stages:Module]

backend/src/services/git_service.py

@@ -1,22 +1,33 @@
 # [DEF:backend.src.services.git_service:Module]
 #
+# @TIER:      STANDARD
 # @SEMANTICS: git, service, gitpython, repository, version_control
 # @PURPOSE:   Core Git logic using GitPython to manage dashboard repositories.
 # @LAYER:     Service
 # @RELATION:  INHERITS_FROM -> None
 # @RELATION:  USED_BY -> src.api.routes.git
 # @RELATION:  USED_BY -> src.plugins.git_plugin
+# @RELATION:  DEPENDS_ON -> src.core.database.SessionLocal
+# @RELATION:  DEPENDS_ON -> src.models.config.AppConfigRecord
+# @RELATION:  DEPENDS_ON -> src.models.git.GitRepository
 #
 # @INVARIANT: All Git operations must be performed on a valid local directory.
 
 import os
 import httpx
+import re
+import shutil
 from git import Repo
 from fastapi import HTTPException
-from typing import List
+from typing import Any, Dict, List, Optional
 from datetime import datetime
+from pathlib import Path
+from urllib.parse import quote, urlparse
 from src.core.logger import logger, belief_scope
 from src.models.git import GitProvider
+from src.models.git import GitRepository
+from src.models.config import AppConfigRecord
+from src.core.database import SessionLocal
 
 # [DEF:GitService:Class]
 # @PURPOSE: Wrapper for GitPython operations with semantic logging and error handling.
@@ -32,28 +43,164 @@ class GitService:
     # @POST: GitService is initialized; base_path directory exists.
     def __init__(self, base_path: str = "git_repos"):
         with belief_scope("GitService.__init__"):
-            # Resolve relative to the backend directory
-            # Path(__file__) is backend/src/services/git_service.py
-            # parents[2] is backend/
-            from pathlib import Path
             backend_root = Path(__file__).parents[2]
-            
-            self.base_path = str((backend_root / base_path).resolve())
+            self.legacy_base_path = str((backend_root / "git_repos").resolve())
+            self.base_path = self._resolve_base_path(base_path)
             if not os.path.exists(self.base_path):
                 os.makedirs(self.base_path)
     # [/DEF:__init__:Function]
 
+    # [DEF:_resolve_base_path:Function]
+    # @PURPOSE: Resolve base repository directory from explicit argument or global storage settings.
+    # @PRE: base_path is a string path.
+    # @POST: Returns absolute path for Git repositories root.
+    # @RETURN: str
+    def _resolve_base_path(self, base_path: str) -> str:
+        # Resolve relative to backend directory for backward compatibility.
+        backend_root = Path(__file__).parents[2]
+        fallback_path = str((backend_root / base_path).resolve())
+
+        if base_path != "git_repos":
+            return fallback_path
+
+        try:
+            session = SessionLocal()
+            try:
+                config_row = session.query(AppConfigRecord).filter(AppConfigRecord.id == "global").first()
+            finally:
+                session.close()
+
+            payload = (config_row.payload if config_row and config_row.payload else {}) if config_row else {}
+            storage_cfg = payload.get("settings", {}).get("storage", {}) if isinstance(payload, dict) else {}
+
+            root_path = str(storage_cfg.get("root_path", "")).strip()
+            repo_path = str(storage_cfg.get("repo_path", "")).strip()
+            if not root_path:
+                return fallback_path
+
+            project_root = Path(__file__).parents[3]
+            root = Path(root_path)
+            if not root.is_absolute():
+                root = (project_root / root).resolve()
+
+            repo_root = Path(repo_path) if repo_path else Path("repositorys")
+            if repo_root.is_absolute():
+                return str(repo_root.resolve())
+            return str((root / repo_root).resolve())
+        except Exception as e:
+            logger.warning(f"[_resolve_base_path][Coherence:Failed] Falling back to default path: {e}")
+            return fallback_path
+    # [/DEF:_resolve_base_path:Function]
+
+    # [DEF:_normalize_repo_key:Function]
+    # @PURPOSE: Convert user/dashboard-provided key to safe filesystem directory name.
+    # @PRE: repo_key can be None/empty.
+    # @POST: Returns normalized non-empty key.
+    # @RETURN: str
+    def _normalize_repo_key(self, repo_key: Optional[str]) -> str:
+        raw_key = str(repo_key or "").strip().lower()
+        normalized = re.sub(r"[^a-z0-9._-]+", "-", raw_key).strip("._-")
+        return normalized or "dashboard"
+    # [/DEF:_normalize_repo_key:Function]
+
+    # [DEF:_update_repo_local_path:Function]
+    # @PURPOSE: Persist repository local_path in GitRepository table when record exists.
+    # @PRE: dashboard_id is valid integer.
+    # @POST: local_path is updated for existing record.
+    # @RETURN: None
+    def _update_repo_local_path(self, dashboard_id: int, local_path: str) -> None:
+        try:
+            session = SessionLocal()
+            try:
+                db_repo = (
+                    session.query(GitRepository)
+                    .filter(GitRepository.dashboard_id == int(dashboard_id))
+                    .first()
+                )
+                if db_repo:
+                    db_repo.local_path = local_path
+                    session.commit()
+            finally:
+                session.close()
+        except Exception as e:
+            logger.warning(f"[_update_repo_local_path][Coherence:Failed] {e}")
+    # [/DEF:_update_repo_local_path:Function]
+
+    # [DEF:_migrate_repo_directory:Function]
+    # @PURPOSE: Move legacy repository directory to target path and sync DB metadata.
+    # @PRE: source_path exists.
+    # @POST: Repository content available at target_path.
+    # @RETURN: str
+    def _migrate_repo_directory(self, dashboard_id: int, source_path: str, target_path: str) -> str:
+        source_abs = os.path.abspath(source_path)
+        target_abs = os.path.abspath(target_path)
+        if source_abs == target_abs:
+            return source_abs
+
+        if os.path.exists(target_abs):
+            logger.warning(
+                f"[_migrate_repo_directory][Action] Target already exists, keeping source path: {target_abs}"
+            )
+            return source_abs
+
+        Path(target_abs).parent.mkdir(parents=True, exist_ok=True)
+        try:
+            os.replace(source_abs, target_abs)
+        except OSError:
+            shutil.move(source_abs, target_abs)
+
+        self._update_repo_local_path(dashboard_id, target_abs)
+        logger.info(
+            f"[_migrate_repo_directory][Coherence:OK] Repository migrated for dashboard {dashboard_id}: {source_abs} -> {target_abs}"
+        )
+        return target_abs
+    # [/DEF:_migrate_repo_directory:Function]
+
     # [DEF:_get_repo_path:Function]
     # @PURPOSE: Resolves the local filesystem path for a dashboard's repository.
     # @PARAM: dashboard_id (int)
+    # @PARAM: repo_key (Optional[str]) - Slug-like key used when DB local_path is absent.
     # @PRE: dashboard_id is an integer.
-    # @POST: Returns the absolute or relative path to the dashboard's repo.
+    # @POST: Returns DB-local_path when present, otherwise base_path/<normalized repo_key>.
     # @RETURN: str
-    def _get_repo_path(self, dashboard_id: int) -> str:
+    def _get_repo_path(self, dashboard_id: int, repo_key: Optional[str] = None) -> str:
         with belief_scope("GitService._get_repo_path"):
             if dashboard_id is None:
                 raise ValueError("dashboard_id cannot be None")
-            return os.path.join(self.base_path, str(dashboard_id))
+            fallback_key = repo_key if repo_key is not None else str(dashboard_id)
+            normalized_key = self._normalize_repo_key(fallback_key)
+            target_path = os.path.join(self.base_path, normalized_key)
+
+            try:
+                session = SessionLocal()
+                try:
+                    db_repo = (
+                        session.query(GitRepository)
+                        .filter(GitRepository.dashboard_id == int(dashboard_id))
+                        .first()
+                    )
+                finally:
+                    session.close()
+                if db_repo and db_repo.local_path:
+                    db_path = os.path.abspath(db_repo.local_path)
+                    if os.path.exists(db_path):
+                        if (
+                            os.path.abspath(self.base_path) != os.path.abspath(self.legacy_base_path)
+                            and db_path.startswith(os.path.abspath(self.legacy_base_path) + os.sep)
+                        ):
+                            return self._migrate_repo_directory(dashboard_id, db_path, target_path)
+                        return db_path
+            except Exception as e:
+                logger.warning(f"[_get_repo_path][Coherence:Failed] Could not resolve local_path from DB: {e}")
+
+            legacy_id_path = os.path.join(self.legacy_base_path, str(dashboard_id))
+            if os.path.exists(legacy_id_path) and not os.path.exists(target_path):
+                return self._migrate_repo_directory(dashboard_id, legacy_id_path, target_path)
+
+            if os.path.exists(target_path):
+                self._update_repo_local_path(dashboard_id, target_path)
+
+            return target_path
     # [/DEF:_get_repo_path:Function]
 
     # [DEF:init_repo:Function]
@@ -61,12 +208,14 @@ class GitService:
     # @PARAM: dashboard_id (int)
     # @PARAM: remote_url (str)
     # @PARAM: pat (str) - Personal Access Token for authentication.
+    # @PARAM: repo_key (Optional[str]) - Slug-like key for deterministic folder naming on first init.
     # @PRE: dashboard_id is int, remote_url is valid Git URL, pat is provided.
     # @POST: Repository is cloned or opened at the local path.
     # @RETURN: Repo - GitPython Repo object.
-    def init_repo(self, dashboard_id: int, remote_url: str, pat: str) -> Repo:
+    def init_repo(self, dashboard_id: int, remote_url: str, pat: str, repo_key: Optional[str] = None) -> Repo:
         with belief_scope("GitService.init_repo"):
-            repo_path = self._get_repo_path(dashboard_id)
+            repo_path = self._get_repo_path(dashboard_id, repo_key=repo_key or str(dashboard_id))
+            Path(repo_path).parent.mkdir(parents=True, exist_ok=True)
             
             # Inject PAT into remote URL if needed
             if pat and "://" in remote_url:
@@ -251,12 +400,21 @@ class GitService:
             try:
                 current_branch = repo.active_branch
                 logger.info(f"[push_changes][Action] Pushing branch {current_branch.name} to origin")
-                # Using a timeout for network operations
-                push_info = origin.push(refspec=f'{current_branch.name}:{current_branch.name}')
-                for info in push_info:
-                    if info.flags & info.ERROR:
-                        logger.error(f"[push_changes][Coherence:Failed] Error pushing ref {info.remote_ref_string}: {info.summary}")
-                        raise Exception(f"Git push error for {info.remote_ref_string}: {info.summary}")
+                tracking_branch = None
+                try:
+                    tracking_branch = current_branch.tracking_branch()
+                except Exception:
+                    tracking_branch = None
+
+                # First push for a new branch must set upstream, otherwise future pull fails.
+                if tracking_branch is None:
+                    repo.git.push("--set-upstream", "origin", f"{current_branch.name}:{current_branch.name}")
+                else:
+                    push_info = origin.push(refspec=f'{current_branch.name}:{current_branch.name}')
+                    for info in push_info:
+                        if info.flags & info.ERROR:
+                            logger.error(f"[push_changes][Coherence:Failed] Error pushing ref {info.remote_ref_string}: {info.summary}")
+                            raise Exception(f"Git push error for {info.remote_ref_string}: {info.summary}")
             except Exception as e:
                 logger.error(f"[push_changes][Coherence:Failed] Failed to push changes: {e}")
                 raise HTTPException(status_code=500, detail=f"Git push failed: {str(e)}")
@@ -271,8 +429,17 @@ class GitService:
             repo = self.get_repo(dashboard_id)
             try:
                 origin = repo.remote(name='origin')
-                logger.info("[pull_changes][Action] Pulling changes from origin")
-                fetch_info = origin.pull()
+                current_branch = repo.active_branch.name
+                remote_ref = f"origin/{current_branch}"
+                has_remote_branch = any(ref.name == remote_ref for ref in repo.refs)
+                if not has_remote_branch:
+                    raise HTTPException(
+                        status_code=409,
+                        detail=f"Remote branch '{current_branch}' does not exist yet. Push this branch first.",
+                    )
+
+                logger.info(f"[pull_changes][Action] Pulling changes from origin/{current_branch}")
+                fetch_info = origin.pull(current_branch)
                 for info in fetch_info:
                     if info.flags & info.ERROR:
                         logger.error(f"[pull_changes][Coherence:Failed] Error pulling ref {info.ref}: {info.note}")
@@ -280,6 +447,8 @@ class GitService:
             except ValueError:
                 logger.error(f"[pull_changes][Coherence:Failed] Remote 'origin' not found for dashboard {dashboard_id}")
                 raise HTTPException(status_code=400, detail="Remote 'origin' not configured")
+            except HTTPException:
+                raise
             except Exception as e:
                 logger.error(f"[pull_changes][Coherence:Failed] Failed to pull changes: {e}")
                 raise HTTPException(status_code=500, detail=f"Git pull failed: {str(e)}")
@@ -302,12 +471,62 @@ class GitService:
             except (ValueError, Exception):
                 has_commits = False
 
+            current_branch = repo.active_branch.name
+            tracking_branch = None
+            has_upstream = False
+            ahead_count = 0
+            behind_count = 0
+
+            try:
+                tracking_branch = repo.active_branch.tracking_branch()
+                has_upstream = tracking_branch is not None
+            except Exception:
+                tracking_branch = None
+                has_upstream = False
+
+            if has_upstream and tracking_branch is not None:
+                try:
+                    # Commits present locally but not in upstream.
+                    ahead_count = sum(
+                        1 for _ in repo.iter_commits(f"{tracking_branch.name}..{current_branch}")
+                    )
+                    # Commits present in upstream but not local.
+                    behind_count = sum(
+                        1 for _ in repo.iter_commits(f"{current_branch}..{tracking_branch.name}")
+                    )
+                except Exception:
+                    ahead_count = 0
+                    behind_count = 0
+
+            is_dirty = repo.is_dirty(untracked_files=True)
+            untracked_files = repo.untracked_files
+            modified_files = [item.a_path for item in repo.index.diff(None)]
+            staged_files = [item.a_path for item in repo.index.diff("HEAD")] if has_commits else []
+            is_diverged = ahead_count > 0 and behind_count > 0
+
+            if is_diverged:
+                sync_state = "DIVERGED"
+            elif behind_count > 0:
+                sync_state = "BEHIND_REMOTE"
+            elif ahead_count > 0:
+                sync_state = "AHEAD_REMOTE"
+            elif is_dirty or modified_files or staged_files or untracked_files:
+                sync_state = "CHANGES"
+            else:
+                sync_state = "SYNCED"
+
             return {
-                "is_dirty": repo.is_dirty(untracked_files=True),
-                "untracked_files": repo.untracked_files,
-                "modified_files": [item.a_path for item in repo.index.diff(None)],
-                "staged_files": [item.a_path for item in repo.index.diff("HEAD")] if has_commits else [],
-                "current_branch": repo.active_branch.name
+                "is_dirty": is_dirty,
+                "untracked_files": untracked_files,
+                "modified_files": modified_files,
+                "staged_files": staged_files,
+                "current_branch": current_branch,
+                "upstream_branch": tracking_branch.name if tracking_branch is not None else None,
+                "has_upstream": has_upstream,
+                "ahead_count": ahead_count,
+                "behind_count": behind_count,
+                "is_diverged": is_diverged,
+                "sync_state": sync_state,
             }
     # [/DEF:get_status:Function]
 
@@ -410,5 +629,565 @@ class GitService:
                 return False
     # [/DEF:test_connection:Function]
 
+    # [DEF:_normalize_git_server_url:Function]
+    # @PURPOSE: Normalize Git server URL for provider API calls.
+    # @PRE: raw_url is non-empty.
+    # @POST: Returns URL without trailing slash.
+    # @RETURN: str
+    def _normalize_git_server_url(self, raw_url: str) -> str:
+        normalized = (raw_url or "").strip()
+        if not normalized:
+            raise HTTPException(status_code=400, detail="Git server URL is required")
+        return normalized.rstrip("/")
+    # [/DEF:_normalize_git_server_url:Function]
+
+    # [DEF:_gitea_headers:Function]
+    # @PURPOSE: Build Gitea API authorization headers.
+    # @PRE: pat is provided.
+    # @POST: Returns headers with token auth.
+    # @RETURN: Dict[str, str]
+    def _gitea_headers(self, pat: str) -> Dict[str, str]:
+        token = (pat or "").strip()
+        if not token:
+            raise HTTPException(status_code=400, detail="Git PAT is required for Gitea operations")
+        return {
+            "Authorization": f"token {token}",
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+        }
+    # [/DEF:_gitea_headers:Function]
+
+    # [DEF:_gitea_request:Function]
+    # @PURPOSE: Execute HTTP request against Gitea API with stable error mapping.
+    # @PRE: method and endpoint are valid.
+    # @POST: Returns decoded JSON payload.
+    # @RETURN: Any
+    async def _gitea_request(
+        self,
+        method: str,
+        server_url: str,
+        pat: str,
+        endpoint: str,
+        payload: Optional[Dict[str, Any]] = None,
+    ) -> Any:
+        base_url = self._normalize_git_server_url(server_url)
+        url = f"{base_url}/api/v1{endpoint}"
+        headers = self._gitea_headers(pat)
+        try:
+            async with httpx.AsyncClient(timeout=20.0) as client:
+                response = await client.request(
+                    method=method,
+                    url=url,
+                    headers=headers,
+                    json=payload,
+                )
+        except Exception as e:
+            logger.error(f"[gitea_request][Coherence:Failed] Network error: {e}")
+            raise HTTPException(status_code=503, detail=f"Gitea API is unavailable: {str(e)}")
+
+        if response.status_code >= 400:
+            detail = response.text
+            try:
+                parsed = response.json()
+                detail = parsed.get("message") or parsed.get("error") or detail
+            except Exception:
+                pass
+            logger.error(
+                f"[gitea_request][Coherence:Failed] method={method} endpoint={endpoint} status={response.status_code} detail={detail}"
+            )
+            raise HTTPException(
+                status_code=response.status_code,
+                detail=f"Gitea API error: {detail}",
+            )
+
+        if response.status_code == 204:
+            return None
+        return response.json()
+    # [/DEF:_gitea_request:Function]
+
+    # [DEF:get_gitea_current_user:Function]
+    # @PURPOSE: Resolve current Gitea user for PAT.
+    # @PRE: server_url and pat are valid.
+    # @POST: Returns current username.
+    # @RETURN: str
+    async def get_gitea_current_user(self, server_url: str, pat: str) -> str:
+        payload = await self._gitea_request("GET", server_url, pat, "/user")
+        username = payload.get("login") or payload.get("username")
+        if not username:
+            raise HTTPException(status_code=500, detail="Failed to resolve Gitea username")
+        return str(username)
+    # [/DEF:get_gitea_current_user:Function]
+
+    # [DEF:list_gitea_repositories:Function]
+    # @PURPOSE: List repositories visible to authenticated Gitea user.
+    # @PRE: server_url and pat are valid.
+    # @POST: Returns repository list from Gitea.
+    # @RETURN: List[dict]
+    async def list_gitea_repositories(self, server_url: str, pat: str) -> List[dict]:
+        payload = await self._gitea_request(
+            "GET",
+            server_url,
+            pat,
+            "/user/repos?limit=100&page=1",
+        )
+        if not isinstance(payload, list):
+            return []
+        return payload
+    # [/DEF:list_gitea_repositories:Function]
+
+    # [DEF:create_gitea_repository:Function]
+    # @PURPOSE: Create repository in Gitea for authenticated user.
+    # @PRE: name is non-empty and PAT has repo creation permission.
+    # @POST: Returns created repository payload.
+    # @RETURN: dict
+    async def create_gitea_repository(
+        self,
+        server_url: str,
+        pat: str,
+        name: str,
+        private: bool = True,
+        description: Optional[str] = None,
+        auto_init: bool = True,
+        default_branch: Optional[str] = "main",
+    ) -> Dict[str, Any]:
+        payload = {
+            "name": name,
+            "private": bool(private),
+            "auto_init": bool(auto_init),
+        }
+        if description:
+            payload["description"] = description
+        if default_branch:
+            payload["default_branch"] = default_branch
+        created = await self._gitea_request(
+            "POST",
+            server_url,
+            pat,
+            "/user/repos",
+            payload=payload,
+        )
+        if not isinstance(created, dict):
+            raise HTTPException(status_code=500, detail="Unexpected Gitea response while creating repository")
+        return created
+    # [/DEF:create_gitea_repository:Function]
+
+    # [DEF:delete_gitea_repository:Function]
+    # @PURPOSE: Delete repository in Gitea.
+    # @PRE: owner and repo_name are non-empty.
+    # @POST: Repository deleted on Gitea server.
+    async def delete_gitea_repository(
+        self,
+        server_url: str,
+        pat: str,
+        owner: str,
+        repo_name: str,
+    ) -> None:
+        if not owner or not repo_name:
+            raise HTTPException(status_code=400, detail="owner and repo_name are required")
+        await self._gitea_request(
+            "DELETE",
+            server_url,
+            pat,
+            f"/repos/{owner}/{repo_name}",
+        )
+    # [/DEF:delete_gitea_repository:Function]
+
+    # [DEF:create_github_repository:Function]
+    # @PURPOSE: Create repository in GitHub or GitHub Enterprise.
+    # @PRE: PAT has repository create permission.
+    # @POST: Returns created repository payload.
+    # @RETURN: dict
+    async def create_github_repository(
+        self,
+        server_url: str,
+        pat: str,
+        name: str,
+        private: bool = True,
+        description: Optional[str] = None,
+        auto_init: bool = True,
+        default_branch: Optional[str] = "main",
+    ) -> Dict[str, Any]:
+        base_url = self._normalize_git_server_url(server_url)
+        if "github.com" in base_url:
+            api_url = "https://api.github.com/user/repos"
+        else:
+            api_url = f"{base_url}/api/v3/user/repos"
+        headers = {
+            "Authorization": f"token {pat.strip()}",
+            "Content-Type": "application/json",
+            "Accept": "application/vnd.github+json",
+        }
+        payload: Dict[str, Any] = {
+            "name": name,
+            "private": bool(private),
+            "auto_init": bool(auto_init),
+        }
+        if description:
+            payload["description"] = description
+        # GitHub API does not reliably support setting default branch on create without template/import.
+        if default_branch:
+            payload["default_branch"] = default_branch
+        try:
+            async with httpx.AsyncClient(timeout=20.0) as client:
+                response = await client.post(api_url, headers=headers, json=payload)
+        except Exception as e:
+            raise HTTPException(status_code=503, detail=f"GitHub API is unavailable: {str(e)}")
+
+        if response.status_code >= 400:
+            detail = response.text
+            try:
+                parsed = response.json()
+                detail = parsed.get("message") or detail
+            except Exception:
+                pass
+            raise HTTPException(status_code=response.status_code, detail=f"GitHub API error: {detail}")
+        return response.json()
+    # [/DEF:create_github_repository:Function]
+
+    # [DEF:create_gitlab_repository:Function]
+    # @PURPOSE: Create repository(project) in GitLab.
+    # @PRE: PAT has api scope.
+    # @POST: Returns created repository payload.
+    # @RETURN: dict
+    async def create_gitlab_repository(
+        self,
+        server_url: str,
+        pat: str,
+        name: str,
+        private: bool = True,
+        description: Optional[str] = None,
+        auto_init: bool = True,
+        default_branch: Optional[str] = "main",
+    ) -> Dict[str, Any]:
+        base_url = self._normalize_git_server_url(server_url)
+        api_url = f"{base_url}/api/v4/projects"
+        headers = {
+            "PRIVATE-TOKEN": pat.strip(),
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+        }
+        payload: Dict[str, Any] = {
+            "name": name,
+            "visibility": "private" if private else "public",
+            "initialize_with_readme": bool(auto_init),
+        }
+        if description:
+            payload["description"] = description
+        if default_branch:
+            payload["default_branch"] = default_branch
+        try:
+            async with httpx.AsyncClient(timeout=20.0) as client:
+                response = await client.post(api_url, headers=headers, json=payload)
+        except Exception as e:
+            raise HTTPException(status_code=503, detail=f"GitLab API is unavailable: {str(e)}")
+
+        if response.status_code >= 400:
+            detail = response.text
+            try:
+                parsed = response.json()
+                if isinstance(parsed, dict):
+                    detail = parsed.get("message") or detail
+            except Exception:
+                pass
+            raise HTTPException(status_code=response.status_code, detail=f"GitLab API error: {detail}")
+
+        data = response.json()
+        # Normalize clone URL key to keep route response stable.
+        if "clone_url" not in data:
+            data["clone_url"] = data.get("http_url_to_repo")
+        if "html_url" not in data:
+            data["html_url"] = data.get("web_url")
+        if "ssh_url" not in data:
+            data["ssh_url"] = data.get("ssh_url_to_repo")
+        if "full_name" not in data:
+            data["full_name"] = data.get("path_with_namespace") or data.get("name")
+        return data
+    # [/DEF:create_gitlab_repository:Function]
+
+    # [DEF:_parse_remote_repo_identity:Function]
+    # @PURPOSE: Parse owner/repo from remote URL for Git server API operations.
+    # @PRE: remote_url is a valid git URL.
+    # @POST: Returns owner/repo tokens.
+    # @RETURN: Dict[str, str]
+    def _parse_remote_repo_identity(self, remote_url: str) -> Dict[str, str]:
+        normalized = str(remote_url or "").strip()
+        if not normalized:
+            raise HTTPException(status_code=400, detail="Repository remote_url is empty")
+
+        if normalized.startswith("git@"):
+            # git@host:owner/repo.git
+            path = normalized.split(":", 1)[1] if ":" in normalized else ""
+        else:
+            parsed = urlparse(normalized)
+            path = parsed.path or ""
+
+        path = path.strip("/")
+        if path.endswith(".git"):
+            path = path[:-4]
+        parts = [segment for segment in path.split("/") if segment]
+        if len(parts) < 2:
+            raise HTTPException(status_code=400, detail=f"Cannot parse repository owner/name from remote URL: {remote_url}")
+
+        owner = parts[0]
+        repo = parts[-1]
+        namespace = "/".join(parts[:-1])
+        return {
+            "owner": owner,
+            "repo": repo,
+            "namespace": namespace,
+            "full_name": f"{namespace}/{repo}",
+        }
+    # [/DEF:_parse_remote_repo_identity:Function]
+
+    # [DEF:_derive_server_url_from_remote:Function]
+    # @PURPOSE: Build API base URL from remote repository URL without credentials.
+    # @PRE: remote_url may be any git URL.
+    # @POST: Returns normalized http(s) base URL or None when derivation is impossible.
+    # @RETURN: Optional[str]
+    def _derive_server_url_from_remote(self, remote_url: str) -> Optional[str]:
+        normalized = str(remote_url or "").strip()
+        if not normalized or normalized.startswith("git@"):
+            return None
+
+        parsed = urlparse(normalized)
+        if parsed.scheme not in {"http", "https"}:
+            return None
+        if not parsed.hostname:
+            return None
+
+        netloc = parsed.hostname
+        if parsed.port:
+            netloc = f"{netloc}:{parsed.port}"
+        return f"{parsed.scheme}://{netloc}".rstrip("/")
+    # [/DEF:_derive_server_url_from_remote:Function]
+
+    # [DEF:promote_direct_merge:Function]
+    # @PURPOSE: Perform direct merge between branches in local repo and push target branch.
+    # @PRE: Repository exists and both branches are valid.
+    # @POST: Target branch contains merged changes from source branch.
+    # @RETURN: Dict[str, Any]
+    def promote_direct_merge(
+        self,
+        dashboard_id: int,
+        from_branch: str,
+        to_branch: str,
+    ) -> Dict[str, Any]:
+        with belief_scope("GitService.promote_direct_merge"):
+            if not from_branch or not to_branch:
+                raise HTTPException(status_code=400, detail="from_branch and to_branch are required")
+            repo = self.get_repo(dashboard_id)
+            source = from_branch.strip()
+            target = to_branch.strip()
+            if source == target:
+                raise HTTPException(status_code=400, detail="from_branch and to_branch must be different")
+
+            try:
+                origin = repo.remote(name="origin")
+            except ValueError:
+                raise HTTPException(status_code=400, detail="Remote 'origin' not configured")
+
+            try:
+                origin.fetch()
+                # Ensure local source branch exists.
+                if source not in [head.name for head in repo.heads]:
+                    if f"origin/{source}" in [ref.name for ref in repo.refs]:
+                        repo.git.checkout("-b", source, f"origin/{source}")
+                    else:
+                        raise HTTPException(status_code=404, detail=f"Source branch '{source}' not found")
+
+                # Ensure local target branch exists and is checked out.
+                if target in [head.name for head in repo.heads]:
+                    repo.git.checkout(target)
+                elif f"origin/{target}" in [ref.name for ref in repo.refs]:
+                    repo.git.checkout("-b", target, f"origin/{target}")
+                else:
+                    raise HTTPException(status_code=404, detail=f"Target branch '{target}' not found")
+
+                # Bring target up to date and merge source into target.
+                try:
+                    origin.pull(target)
+                except Exception:
+                    pass
+                repo.git.merge(source, "--no-ff", "-m", f"chore(flow): promote {source} -> {target}")
+                origin.push(refspec=f"{target}:{target}")
+            except HTTPException:
+                raise
+            except Exception as e:
+                message = str(e)
+                if "CONFLICT" in message.upper():
+                    raise HTTPException(status_code=409, detail=f"Merge conflict during direct promote: {message}")
+                raise HTTPException(status_code=500, detail=f"Direct promote failed: {message}")
+
+            return {
+                "mode": "direct",
+                "from_branch": source,
+                "to_branch": target,
+                "status": "merged",
+            }
+    # [/DEF:promote_direct_merge:Function]
+
+    # [DEF:create_gitea_pull_request:Function]
+    # @PURPOSE: Create pull request in Gitea.
+    # @PRE: Config and remote URL are valid.
+    # @POST: Returns normalized PR metadata.
+    # @RETURN: Dict[str, Any]
+    async def create_gitea_pull_request(
+        self,
+        server_url: str,
+        pat: str,
+        remote_url: str,
+        from_branch: str,
+        to_branch: str,
+        title: str,
+        description: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        identity = self._parse_remote_repo_identity(remote_url)
+        payload = {
+            "title": title,
+            "head": from_branch,
+            "base": to_branch,
+            "body": description or "",
+        }
+        endpoint = f"/repos/{identity['namespace']}/{identity['repo']}/pulls"
+        try:
+            data = await self._gitea_request(
+                "POST",
+                server_url,
+                pat,
+                endpoint,
+                payload=payload,
+            )
+        except HTTPException as exc:
+            fallback_url = self._derive_server_url_from_remote(remote_url)
+            normalized_primary = self._normalize_git_server_url(server_url)
+            if exc.status_code != 404 or not fallback_url or fallback_url == normalized_primary:
+                raise
+
+            logger.warning(
+                "[create_gitea_pull_request][Action] Primary Gitea URL not found, retrying with remote host: %s",
+                fallback_url,
+            )
+            data = await self._gitea_request(
+                "POST",
+                fallback_url,
+                pat,
+                endpoint,
+                payload=payload,
+            )
+        return {
+            "id": data.get("number") or data.get("id"),
+            "url": data.get("html_url") or data.get("url"),
+            "status": data.get("state") or "open",
+        }
+    # [/DEF:create_gitea_pull_request:Function]
+
+    # [DEF:create_github_pull_request:Function]
+    # @PURPOSE: Create pull request in GitHub or GitHub Enterprise.
+    # @PRE: Config and remote URL are valid.
+    # @POST: Returns normalized PR metadata.
+    # @RETURN: Dict[str, Any]
+    async def create_github_pull_request(
+        self,
+        server_url: str,
+        pat: str,
+        remote_url: str,
+        from_branch: str,
+        to_branch: str,
+        title: str,
+        description: Optional[str] = None,
+        draft: bool = False,
+    ) -> Dict[str, Any]:
+        identity = self._parse_remote_repo_identity(remote_url)
+        base_url = self._normalize_git_server_url(server_url)
+        if "github.com" in base_url:
+            api_url = f"https://api.github.com/repos/{identity['namespace']}/{identity['repo']}/pulls"
+        else:
+            api_url = f"{base_url}/api/v3/repos/{identity['namespace']}/{identity['repo']}/pulls"
+        headers = {
+            "Authorization": f"token {pat.strip()}",
+            "Content-Type": "application/json",
+            "Accept": "application/vnd.github+json",
+        }
+        payload = {
+            "title": title,
+            "head": from_branch,
+            "base": to_branch,
+            "body": description or "",
+            "draft": bool(draft),
+        }
+        try:
+            async with httpx.AsyncClient(timeout=20.0) as client:
+                response = await client.post(api_url, headers=headers, json=payload)
+        except Exception as e:
+            raise HTTPException(status_code=503, detail=f"GitHub API is unavailable: {str(e)}")
+        if response.status_code >= 400:
+            detail = response.text
+            try:
+                detail = response.json().get("message") or detail
+            except Exception:
+                pass
+            raise HTTPException(status_code=response.status_code, detail=f"GitHub API error: {detail}")
+        data = response.json()
+        return {
+            "id": data.get("number") or data.get("id"),
+            "url": data.get("html_url") or data.get("url"),
+            "status": data.get("state") or "open",
+        }
+    # [/DEF:create_github_pull_request:Function]
+
+    # [DEF:create_gitlab_merge_request:Function]
+    # @PURPOSE: Create merge request in GitLab.
+    # @PRE: Config and remote URL are valid.
+    # @POST: Returns normalized MR metadata.
+    # @RETURN: Dict[str, Any]
+    async def create_gitlab_merge_request(
+        self,
+        server_url: str,
+        pat: str,
+        remote_url: str,
+        from_branch: str,
+        to_branch: str,
+        title: str,
+        description: Optional[str] = None,
+        remove_source_branch: bool = False,
+    ) -> Dict[str, Any]:
+        identity = self._parse_remote_repo_identity(remote_url)
+        base_url = self._normalize_git_server_url(server_url)
+        project_id = quote(identity["full_name"], safe="")
+        api_url = f"{base_url}/api/v4/projects/{project_id}/merge_requests"
+        headers = {
+            "PRIVATE-TOKEN": pat.strip(),
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+        }
+        payload = {
+            "source_branch": from_branch,
+            "target_branch": to_branch,
+            "title": title,
+            "description": description or "",
+            "remove_source_branch": bool(remove_source_branch),
+        }
+        try:
+            async with httpx.AsyncClient(timeout=20.0) as client:
+                response = await client.post(api_url, headers=headers, json=payload)
+        except Exception as e:
+            raise HTTPException(status_code=503, detail=f"GitLab API is unavailable: {str(e)}")
+        if response.status_code >= 400:
+            detail = response.text
+            try:
+                parsed = response.json()
+                if isinstance(parsed, dict):
+                    detail = parsed.get("message") or detail
+            except Exception:
+                pass
+            raise HTTPException(status_code=response.status_code, detail=f"GitLab API error: {detail}")
+        data = response.json()
+        return {
+            "id": data.get("iid") or data.get("id"),
+            "url": data.get("web_url") or data.get("url"),
+            "status": data.get("state") or "opened",
+        }
+    # [/DEF:create_gitlab_merge_request:Function]
+
 # [/DEF:GitService:Class]
-# [/DEF:backend.src.services.git_service:Module]
+# [/DEF:backend.src.services.git_service:Module]

backend/src/services/llm_provider.py

@@ -18,6 +18,18 @@ import os
 # @TIER: CRITICAL
 # @PURPOSE: Handles encryption and decryption of sensitive data like API keys.
 # @INVARIANT: Uses a secret key from environment or a default one (fallback only for dev).
+#
+# @TEST_CONTRACT: EncryptionManagerModel ->
+# {
+#   required_fields: {},
+#   invariants: [
+#       "encrypted data can be decrypted back to the original string"
+#   ]
+# }
+# @TEST_FIXTURE: basic_encryption_cycle -> {"data": "my_secret_key"}
+# @TEST_EDGE: decrypt_invalid_data -> raises Exception
+# @TEST_EDGE: empty_string_encryption -> {"data": ""}
+# @TEST_INVARIANT: symmetric_encryption -> verifies: [basic_encryption_cycle, empty_string_encryption]
 class EncryptionManager:
     # [DEF:EncryptionManager.__init__:Function]
     # @PURPOSE: Initialize the encryption manager with a Fernet key.

backend/src/services/reports/normalizer.py

@@ -113,6 +113,20 @@ def extract_error_context(task: Task, report_status: ReportStatus) -> Optional[E
 # @POST: Returns TaskReport with required fields and deterministic fallback behavior.
 # @PARAM: task (Task) - Source task.
 # @RETURN: TaskReport - Canonical normalized report.
+#
+# @TEST_CONTRACT: NormalizeTaskReport ->
+# {
+#   required_fields: {task: Task},
+#   invariants: [
+#       "Returns a valid TaskReport object",
+#       "Maps TaskStatus to ReportStatus deterministically",
+#       "Extracts ErrorContext for FAILED/PARTIAL tasks"
+#   ]
+# }
+# @TEST_FIXTURE: valid_task -> {"task": "MockTask(id='1', plugin_id='superset-migration', status=TaskStatus.SUCCESS)"}
+# @TEST_EDGE: task_with_error -> {"task": "MockTask(status=TaskStatus.FAILED, logs=[LogEntry(level='ERROR', message='Failed')])"}
+# @TEST_EDGE: unknown_plugin_type -> {"task": "MockTask(plugin_id='unknown-plugin', status=TaskStatus.PENDING)"}
+# @TEST_INVARIANT: deterministic_normalization -> verifies: [valid_task, task_with_error, unknown_plugin_type]
 def normalize_task_report(task: Task) -> TaskReport:
     with belief_scope("normalize_task_report"):
         task_type = resolve_task_type(task.plugin_id)

backend/src/services/reports/report_service.py

@@ -26,6 +26,19 @@ from .normalizer import normalize_task_report
 # @PRE: TaskManager dependency is initialized.
 # @POST: Provides deterministic list/detail report responses.
 # @INVARIANT: Service methods are read-only over task history source.
+#
+# @TEST_CONTRACT: ReportsServiceModel ->
+# {
+#   required_fields: {task_manager: TaskManager},
+#   invariants: [
+#       "list_reports returns a matching ReportCollection",
+#       "get_report_detail returns a valid ReportDetailView or None"
+#   ]
+# }
+# @TEST_FIXTURE: valid_service -> {"task_manager": "MockTaskManager()"}
+# @TEST_EDGE: empty_task_list -> returns empty ReportCollection
+# @TEST_EDGE: report_not_found -> get_report_detail returns None
+# @TEST_INVARIANT: consistent_pagination -> verifies: [valid_service]
 class ReportsService:
     # [DEF:__init__:Function]
     # @TIER: CRITICAL

backend/src/services/reports/type_profiles.py

@@ -71,6 +71,17 @@ TASK_TYPE_PROFILES: Dict[TaskType, Dict[str, Any]] = {
 # @POST: Always returns one of TaskType enum values.
 # @PARAM: plugin_id (Optional[str]) - Source plugin/task identifier from task record.
 # @RETURN: TaskType - Resolved canonical type or UNKNOWN fallback.
+#
+# @TEST_CONTRACT: ResolveTaskType ->
+# {
+#   required_fields: {plugin_id: str},
+#   invariants: ["returns TaskType.UNKNOWN for missing/unmapped plugin_id"]
+# }
+# @TEST_FIXTURE: valid_plugin -> {"plugin_id": "superset-migration"}
+# @TEST_EDGE: empty_plugin -> {"plugin_id": ""}
+# @TEST_EDGE: none_plugin -> {"plugin_id": None}
+# @TEST_EDGE: unknown_plugin -> {"plugin_id": "invalid-plugin"}
+# @TEST_INVARIANT: fallback_to_unknown -> verifies: [empty_plugin, none_plugin, unknown_plugin]
 def resolve_task_type(plugin_id: Optional[str]) -> TaskType:
     with belief_scope("resolve_task_type"):
         normalized = (plugin_id or "").strip()
@@ -86,6 +97,15 @@ def resolve_task_type(plugin_id: Optional[str]) -> TaskType:
 # @POST: Returns a profile dict and never raises for unknown types.
 # @PARAM: task_type (TaskType) - Canonical task type.
 # @RETURN: Dict[str, Any] - Profile metadata used by normalization and UI contracts.
+#
+# @TEST_CONTRACT: GetTypeProfile ->
+# {
+#   required_fields: {task_type: TaskType},
+#   invariants: ["returns a valid metadata dictionary even for UNKNOWN"]
+# }
+# @TEST_FIXTURE: valid_profile -> {"task_type": "migration"}
+# @TEST_EDGE: missing_profile -> {"task_type": "some_new_type"}
+# @TEST_INVARIANT: always_returns_dict -> verifies: [valid_profile, missing_profile]
 def get_type_profile(task_type: TaskType) -> Dict[str, Any]:
     with belief_scope("get_type_profile"):
         return TASK_TYPE_PROFILES.get(task_type, TASK_TYPE_PROFILES[TaskType.UNKNOWN])

backend/src/services/resource_service.py

@@ -10,6 +10,7 @@
 
 # [SECTION: IMPORTS]
 from typing import List, Dict, Optional, Any
+from datetime import datetime
 from ..core.superset_client import SupersetClient
 from ..core.task_manager.models import Task
 from ..services.git_service import GitService
@@ -39,11 +40,12 @@ class ResourceService:
     # @RETURN: List[Dict] - Dashboards with git_status and last_task fields
     # @RELATION: CALLS -> SupersetClient.get_dashboards_summary
     # @RELATION: CALLS -> self._get_git_status_for_dashboard
-    # @RELATION: CALLS -> self._get_last_task_for_resource
+    # @RELATION: CALLS -> self._get_last_llm_task_for_dashboard
     async def get_dashboards_with_status(
         self, 
         env: Any, 
-        tasks: Optional[List[Task]] = None
+        tasks: Optional[List[Task]] = None,
+        include_git_status: bool = True,
     ) -> List[Dict[str, Any]]:
         with belief_scope("get_dashboards_with_status", f"env={env.id}"):
             client = SupersetClient(env)
@@ -56,14 +58,18 @@ class ResourceService:
                 dashboard_dict = dashboard
                 dashboard_id = dashboard_dict.get('id')
                 
-                # Get Git status if repo exists
-                git_status = self._get_git_status_for_dashboard(dashboard_id)
-                dashboard_dict['git_status'] = git_status
+                # Git status can be skipped for list endpoints and loaded lazily on UI side.
+                if include_git_status:
+                    git_status = self._get_git_status_for_dashboard(dashboard_id)
+                    dashboard_dict['git_status'] = git_status
+                else:
+                    dashboard_dict['git_status'] = None
                 
-                # Get last task status
-                last_task = self._get_last_task_for_resource(
-                    f"dashboard-{dashboard_id}", 
-                    tasks
+                # Show status of the latest LLM validation for this dashboard.
+                last_task = self._get_last_llm_task_for_dashboard(
+                    dashboard_id,
+                    env.id,
+                    tasks,
                 )
                 dashboard_dict['last_task'] = last_task
                 
@@ -72,6 +78,157 @@ class ResourceService:
             logger.info(f"[ResourceService][Coherence:OK] Fetched {len(result)} dashboards with status")
             return result
     # [/DEF:get_dashboards_with_status:Function]
+
+    # [DEF:get_dashboards_page_with_status:Function]
+    # @PURPOSE: Fetch one dashboard page from environment and enrich only that page with status metadata.
+    # @PRE: env is valid; page >= 1; page_size > 0.
+    # @POST: Returns page items plus total counters without scanning all pages locally.
+    # @PARAM: env (Environment) - Source environment.
+    # @PARAM: tasks (Optional[List[Task]]) - Tasks for latest LLM status.
+    # @PARAM: page (int) - 1-based page number.
+    # @PARAM: page_size (int) - Page size.
+    # @RETURN: Dict[str, Any] - {"dashboards": List[Dict], "total": int, "total_pages": int}
+    async def get_dashboards_page_with_status(
+        self,
+        env: Any,
+        tasks: Optional[List[Task]] = None,
+        page: int = 1,
+        page_size: int = 10,
+        search: Optional[str] = None,
+        include_git_status: bool = True,
+    ) -> Dict[str, Any]:
+        with belief_scope(
+            "get_dashboards_page_with_status",
+            f"env={env.id}, page={page}, page_size={page_size}, search={search}",
+        ):
+            client = SupersetClient(env)
+            total, dashboards_page = client.get_dashboards_summary_page(
+                page=page,
+                page_size=page_size,
+                search=search,
+            )
+
+            result = []
+            for dashboard in dashboards_page:
+                dashboard_dict = dashboard
+                dashboard_id = dashboard_dict.get("id")
+
+                if include_git_status:
+                    dashboard_dict["git_status"] = self._get_git_status_for_dashboard(dashboard_id)
+                else:
+                    dashboard_dict["git_status"] = None
+
+                dashboard_dict["last_task"] = self._get_last_llm_task_for_dashboard(
+                    dashboard_id,
+                    env.id,
+                    tasks,
+                )
+                result.append(dashboard_dict)
+
+            total_pages = (total + page_size - 1) // page_size if total > 0 else 1
+            logger.info(
+                "[ResourceService][Coherence:OK] Fetched dashboards page %s/%s (%s items, total=%s)",
+                page,
+                total_pages,
+                len(result),
+                total,
+            )
+            return {
+                "dashboards": result,
+                "total": total,
+                "total_pages": total_pages,
+            }
+    # [/DEF:get_dashboards_page_with_status:Function]
+
+    # [DEF:_get_last_llm_task_for_dashboard:Function]
+    # @PURPOSE: Get most recent LLM validation task for a dashboard in an environment
+    # @PRE: dashboard_id is a valid integer identifier
+    # @POST: Returns the newest llm_dashboard_validation task summary or None
+    # @PARAM: dashboard_id (int) - The dashboard ID
+    # @PARAM: env_id (Optional[str]) - Environment ID to match task params
+    # @PARAM: tasks (Optional[List[Task]]) - List of tasks to search
+    # @RETURN: Optional[Dict] - Task summary with task_id and status
+    def _get_last_llm_task_for_dashboard(
+        self,
+        dashboard_id: int,
+        env_id: Optional[str],
+        tasks: Optional[List[Task]] = None,
+    ) -> Optional[Dict[str, Any]]:
+        if not tasks:
+            return None
+
+        dashboard_id_str = str(dashboard_id)
+        matched_tasks = []
+
+        for task in tasks:
+            if getattr(task, "plugin_id", None) != "llm_dashboard_validation":
+                continue
+
+            params = getattr(task, "params", {}) or {}
+            if str(params.get("dashboard_id")) != dashboard_id_str:
+                continue
+
+            if env_id is not None:
+                task_env = params.get("environment_id") or params.get("env")
+                if str(task_env) != str(env_id):
+                    continue
+
+            matched_tasks.append(task)
+
+        if not matched_tasks:
+            return None
+
+        def _task_time(task_obj: Any) -> datetime:
+            return (
+                getattr(task_obj, "started_at", None)
+                or getattr(task_obj, "finished_at", None)
+                or getattr(task_obj, "created_at", None)
+                or datetime.min
+            )
+
+        last_task = max(matched_tasks, key=_task_time)
+        raw_result = getattr(last_task, "result", None)
+        validation_status = None
+        if isinstance(raw_result, dict):
+            validation_status = self._normalize_validation_status(raw_result.get("status"))
+
+        return {
+            "task_id": str(getattr(last_task, "id", "")),
+            "status": self._normalize_task_status(getattr(last_task, "status", "")),
+            "validation_status": validation_status,
+        }
+    # [/DEF:_get_last_llm_task_for_dashboard:Function]
+
+    # [DEF:_normalize_task_status:Function]
+    # @PURPOSE: Normalize task status to stable uppercase values for UI/API projections
+    # @PRE: raw_status can be enum or string
+    # @POST: Returns uppercase status without enum class prefix
+    # @PARAM: raw_status (Any) - Raw task status object/value
+    # @RETURN: str - Normalized status token
+    def _normalize_task_status(self, raw_status: Any) -> str:
+        if raw_status is None:
+            return ""
+        value = getattr(raw_status, "value", raw_status)
+        status_text = str(value).strip()
+        if "." in status_text:
+            status_text = status_text.split(".")[-1]
+        return status_text.upper()
+    # [/DEF:_normalize_task_status:Function]
+
+    # [DEF:_normalize_validation_status:Function]
+    # @PURPOSE: Normalize LLM validation status to PASS/FAIL/WARN/UNKNOWN
+    # @PRE: raw_status can be any scalar type
+    # @POST: Returns normalized validation status token or None
+    # @PARAM: raw_status (Any) - Raw validation status from task result
+    # @RETURN: Optional[str] - PASS|FAIL|WARN|UNKNOWN
+    def _normalize_validation_status(self, raw_status: Any) -> Optional[str]:
+        if raw_status is None:
+            return None
+        status_text = str(raw_status).strip().upper()
+        if status_text in {"PASS", "FAIL", "WARN"}:
+            return status_text
+        return "UNKNOWN"
+    # [/DEF:_normalize_validation_status:Function]
     
     # [DEF:get_datasets_with_status:Function]
     # @PURPOSE: Fetch datasets from environment with mapping progress and last task status

backend/tests/api/routes/test_clean_release_api.py

@@ -0,0 +1,111 @@
+# [DEF:backend.tests.api.routes.test_clean_release_api:Module]
+# @TIER: STANDARD
+# @SEMANTICS: tests, api, clean-release, checks, reports
+# @PURPOSE: Contract tests for clean release checks and reports endpoints.
+# @LAYER: Domain
+# @RELATION: TESTS -> backend.src.api.routes.clean_release
+# @INVARIANT: API returns deterministic payload shapes for checks and reports.
+
+from datetime import datetime, timezone
+
+from fastapi.testclient import TestClient
+
+from src.app import app
+from src.dependencies import get_clean_release_repository
+from src.models.clean_release import (
+    CleanProfilePolicy,
+    ProfileType,
+    ReleaseCandidate,
+    ReleaseCandidateStatus,
+    ResourceSourceEntry,
+    ResourceSourceRegistry,
+)
+from src.services.clean_release.repository import CleanReleaseRepository
+
+
+def _repo_with_seed_data() -> CleanReleaseRepository:
+    repo = CleanReleaseRepository()
+    repo.save_candidate(
+        ReleaseCandidate(
+            candidate_id="2026.03.03-rc1",
+            version="2026.03.03",
+            profile=ProfileType.ENTERPRISE_CLEAN,
+            created_at=datetime.now(timezone.utc),
+            created_by="tester",
+            source_snapshot_ref="git:abc123",
+            status=ReleaseCandidateStatus.PREPARED,
+        )
+    )
+    repo.save_registry(
+        ResourceSourceRegistry(
+            registry_id="registry-internal-v1",
+            name="Internal",
+            entries=[
+                ResourceSourceEntry(
+                    source_id="src-1",
+                    host="repo.intra.company.local",
+                    protocol="https",
+                    purpose="artifact-repo",
+                    enabled=True,
+                )
+            ],
+            updated_at=datetime.now(timezone.utc),
+            updated_by="tester",
+            status="active",
+        )
+    )
+    repo.save_policy(
+        CleanProfilePolicy(
+            policy_id="policy-enterprise-clean-v1",
+            policy_version="1.0.0",
+            active=True,
+            prohibited_artifact_categories=["test-data"],
+            required_system_categories=["system-init"],
+            external_source_forbidden=True,
+            internal_source_registry_ref="registry-internal-v1",
+            effective_from=datetime.now(timezone.utc),
+            profile=ProfileType.ENTERPRISE_CLEAN,
+        )
+    )
+    return repo
+
+
+def test_start_check_and_get_status_contract():
+    repo = _repo_with_seed_data()
+    app.dependency_overrides[get_clean_release_repository] = lambda: repo
+    try:
+        client = TestClient(app)
+
+        start = client.post(
+            "/api/clean-release/checks",
+            json={
+                "candidate_id": "2026.03.03-rc1",
+                "profile": "enterprise-clean",
+                "execution_mode": "tui",
+                "triggered_by": "tester",
+            },
+        )
+        assert start.status_code == 202
+        payload = start.json()
+        assert set(["check_run_id", "candidate_id", "status", "started_at"]).issubset(payload.keys())
+
+        check_run_id = payload["check_run_id"]
+        status_resp = client.get(f"/api/clean-release/checks/{check_run_id}")
+        assert status_resp.status_code == 200
+        status_payload = status_resp.json()
+        assert status_payload["check_run_id"] == check_run_id
+        assert "final_status" in status_payload
+        assert "checks" in status_payload
+    finally:
+        app.dependency_overrides.clear()
+
+
+def test_get_report_not_found_returns_404():
+    repo = _repo_with_seed_data()
+    app.dependency_overrides[get_clean_release_repository] = lambda: repo
+    try:
+        client = TestClient(app)
+        resp = client.get("/api/clean-release/reports/unknown-report")
+        assert resp.status_code == 404
+    finally:
+        app.dependency_overrides.clear()

backend/tests/api/routes/test_clean_release_source_policy.py

@@ -0,0 +1,97 @@
+# [DEF:backend.tests.api.routes.test_clean_release_source_policy:Module]
+# @TIER: STANDARD
+# @SEMANTICS: tests, api, clean-release, source-policy
+# @PURPOSE: Validate API behavior for source isolation violations in clean release preparation.
+# @LAYER: Domain
+# @RELATION: TESTS -> backend.src.api.routes.clean_release
+# @INVARIANT: External endpoints must produce blocking violation entries.
+
+from datetime import datetime, timezone
+from fastapi.testclient import TestClient
+
+from src.app import app
+from src.dependencies import get_clean_release_repository
+from src.models.clean_release import (
+    CleanProfilePolicy,
+    ProfileType,
+    ReleaseCandidate,
+    ReleaseCandidateStatus,
+    ResourceSourceEntry,
+    ResourceSourceRegistry,
+)
+from src.services.clean_release.repository import CleanReleaseRepository
+
+
+def _repo_with_seed_data() -> CleanReleaseRepository:
+    repo = CleanReleaseRepository()
+
+    repo.save_candidate(
+        ReleaseCandidate(
+            candidate_id="2026.03.03-rc1",
+            version="2026.03.03",
+            profile=ProfileType.ENTERPRISE_CLEAN,
+            created_at=datetime.now(timezone.utc),
+            created_by="tester",
+            source_snapshot_ref="git:abc123",
+            status=ReleaseCandidateStatus.DRAFT,
+        )
+    )
+
+    repo.save_registry(
+        ResourceSourceRegistry(
+            registry_id="registry-internal-v1",
+            name="Internal",
+            entries=[
+                ResourceSourceEntry(
+                    source_id="src-1",
+                    host="repo.intra.company.local",
+                    protocol="https",
+                    purpose="artifact-repo",
+                    enabled=True,
+                )
+            ],
+            updated_at=datetime.now(timezone.utc),
+            updated_by="tester",
+            status="active",
+        )
+    )
+
+    repo.save_policy(
+        CleanProfilePolicy(
+            policy_id="policy-enterprise-clean-v1",
+            policy_version="1.0.0",
+            active=True,
+            prohibited_artifact_categories=["test-data"],
+            required_system_categories=["system-init"],
+            external_source_forbidden=True,
+            internal_source_registry_ref="registry-internal-v1",
+            effective_from=datetime.now(timezone.utc),
+            profile=ProfileType.ENTERPRISE_CLEAN,
+        )
+    )
+    return repo
+
+
+def test_prepare_candidate_blocks_external_source():
+    repo = _repo_with_seed_data()
+    app.dependency_overrides[get_clean_release_repository] = lambda: repo
+
+    try:
+        client = TestClient(app)
+        response = client.post(
+            "/api/clean-release/candidates/prepare",
+            json={
+                "candidate_id": "2026.03.03-rc1",
+                "artifacts": [
+                    {"path": "cfg/system.yaml", "category": "system-init", "reason": "required"}
+                ],
+                "sources": ["repo.intra.company.local", "pypi.org"],
+                "operator_id": "release-manager",
+            },
+        )
+        assert response.status_code == 200
+        data = response.json()
+        assert data["status"] == "blocked"
+        assert any(v["category"] == "external-source" for v in data["violations"])
+    finally:
+        app.dependency_overrides.clear()

backend/tests/core/migration/test_archive_parser.py

@@ -0,0 +1,62 @@
+# [DEF:backend.tests.core.migration.test_archive_parser:Module]
+#
+# @TIER: STANDARD
+# @PURPOSE: Unit tests for MigrationArchiveParser ZIP extraction contract.
+# @LAYER: Domain
+# @RELATION: VERIFIES -> backend.src.core.migration.archive_parser
+#
+import os
+import sys
+import tempfile
+import zipfile
+from pathlib import Path
+
+import yaml
+
+backend_dir = str(Path(__file__).parent.parent.parent.parent.resolve())
+if backend_dir not in sys.path:
+    sys.path.insert(0, backend_dir)
+
+from src.core.migration.archive_parser import MigrationArchiveParser
+
+
+def test_extract_objects_from_zip_collects_all_types():
+    parser = MigrationArchiveParser()
+    with tempfile.TemporaryDirectory() as td:
+        td_path = Path(td)
+        zip_path = td_path / "objects.zip"
+        src_dir = td_path / "src"
+        (src_dir / "dashboards").mkdir(parents=True)
+        (src_dir / "charts").mkdir(parents=True)
+        (src_dir / "datasets").mkdir(parents=True)
+
+        with open(src_dir / "dashboards" / "dash.yaml", "w") as file_obj:
+            yaml.dump({"uuid": "dash-u1", "dashboard_title": "D1", "json_metadata": "{}"}, file_obj)
+        with open(src_dir / "charts" / "chart.yaml", "w") as file_obj:
+            yaml.dump({"uuid": "chart-u1", "slice_name": "C1", "viz_type": "bar"}, file_obj)
+        with open(src_dir / "datasets" / "dataset.yaml", "w") as file_obj:
+            yaml.dump({"uuid": "ds-u1", "table_name": "orders", "database_uuid": "db-u1"}, file_obj)
+
+        with zipfile.ZipFile(zip_path, "w") as zip_obj:
+            for root, _, files in os.walk(src_dir):
+                for file_name in files:
+                    file_path = Path(root) / file_name
+                    zip_obj.write(file_path, file_path.relative_to(src_dir))
+
+        extracted = parser.extract_objects_from_zip(str(zip_path))
+
+    if len(extracted["dashboards"]) != 1:
+        raise AssertionError("dashboards extraction size mismatch")
+    if extracted["dashboards"][0]["uuid"] != "dash-u1":
+        raise AssertionError("dashboard uuid mismatch")
+    if len(extracted["charts"]) != 1:
+        raise AssertionError("charts extraction size mismatch")
+    if extracted["charts"][0]["uuid"] != "chart-u1":
+        raise AssertionError("chart uuid mismatch")
+    if len(extracted["datasets"]) != 1:
+        raise AssertionError("datasets extraction size mismatch")
+    if extracted["datasets"][0]["uuid"] != "ds-u1":
+        raise AssertionError("dataset uuid mismatch")
+
+
+# [/DEF:backend.tests.core.migration.test_archive_parser:Module]

backend/tests/core/migration/test_dry_run_orchestrator.py

@@ -0,0 +1,110 @@
+# [DEF:backend.tests.core.migration.test_dry_run_orchestrator:Module]
+#
+# @TIER: STANDARD
+# @PURPOSE: Unit tests for MigrationDryRunService diff and risk computation contracts.
+# @LAYER: Domain
+# @RELATION: VERIFIES -> backend.src.core.migration.dry_run_orchestrator
+#
+import json
+import sys
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+from sqlalchemy import create_engine
+from sqlalchemy.orm import sessionmaker
+from sqlalchemy.pool import StaticPool
+
+backend_dir = str(Path(__file__).parent.parent.parent.parent.resolve())
+if backend_dir not in sys.path:
+    sys.path.insert(0, backend_dir)
+
+from src.core.migration.dry_run_orchestrator import MigrationDryRunService
+from src.models.dashboard import DashboardSelection
+from src.models.mapping import Base
+
+
+def _load_fixture() -> dict:
+    fixture_path = Path(__file__).parents[2] / "fixtures" / "migration_dry_run_fixture.json"
+    return json.loads(fixture_path.read_text())
+
+
+def _make_session():
+    engine = create_engine(
+        "sqlite:///:memory:",
+        connect_args={"check_same_thread": False},
+        poolclass=StaticPool,
+    )
+    Base.metadata.create_all(engine)
+    Session = sessionmaker(bind=engine)
+    return Session()
+
+
+def test_migration_dry_run_service_builds_diff_and_risk():
+    # @TEST_CONTRACT: dry_run_result_contract -> {
+    #   required_fields: {diff: object, summary: object, risk: object},
+    #   invariants: ["risk.score >= 0", "summary.selected_dashboards == len(selection.selected_ids)"]
+    # }
+    # @TEST_FIXTURE: migration_dry_run_fixture -> backend/tests/fixtures/migration_dry_run_fixture.json
+    # @TEST_EDGE: missing_target_datasource -> fixture.transformed_zip_objects.datasets[0].database_uuid
+    # @TEST_EDGE: breaking_reference -> fixture.transformed_zip_objects.charts[0].dataset_uuid
+    fixture = _load_fixture()
+    db = _make_session()
+    selection = DashboardSelection(
+        selected_ids=[42],
+        source_env_id="src",
+        target_env_id="tgt",
+        replace_db_config=False,
+        fix_cross_filters=True,
+    )
+
+    source_client = MagicMock()
+    source_client.get_dashboards_summary.return_value = fixture["source_dashboard_summary"]
+    source_client.export_dashboard.return_value = (b"PK\x03\x04", "source.zip")
+
+    target_client = MagicMock()
+    target_client.get_dashboards.return_value = (
+        len(fixture["target"]["dashboards"]),
+        fixture["target"]["dashboards"],
+    )
+    target_client.get_datasets.return_value = (
+        len(fixture["target"]["datasets"]),
+        fixture["target"]["datasets"],
+    )
+    target_client.get_charts.return_value = (
+        len(fixture["target"]["charts"]),
+        fixture["target"]["charts"],
+    )
+    target_client.get_databases.return_value = (
+        len(fixture["target"]["databases"]),
+        fixture["target"]["databases"],
+    )
+
+    parser = MagicMock()
+    parser.extract_objects_from_zip.return_value = fixture["transformed_zip_objects"]
+    service = MigrationDryRunService(parser=parser)
+
+    with patch("src.core.migration.dry_run_orchestrator.MigrationEngine") as EngineMock:
+        engine = MagicMock()
+        engine.transform_zip.return_value = True
+        EngineMock.return_value = engine
+        result = service.run(selection, source_client, target_client, db)
+
+    if "summary" not in result:
+        raise AssertionError("summary is missing in dry-run payload")
+    if result["summary"]["selected_dashboards"] != 1:
+        raise AssertionError("selected_dashboards summary mismatch")
+    if result["summary"]["dashboards"]["update"] != 1:
+        raise AssertionError("dashboard update count mismatch")
+    if result["summary"]["charts"]["create"] != 1:
+        raise AssertionError("chart create count mismatch")
+    if result["summary"]["datasets"]["create"] != 1:
+        raise AssertionError("dataset create count mismatch")
+
+    risk_codes = {item["code"] for item in result["risk"]["items"]}
+    if "missing_datasource" not in risk_codes:
+        raise AssertionError("missing_datasource risk is not detected")
+    if "breaking_reference" not in risk_codes:
+        raise AssertionError("breaking_reference risk is not detected")
+
+
+# [/DEF:backend.tests.core.migration.test_dry_run_orchestrator:Module]

backend/tests/core/test_git_service_gitea_pr.py

@@ -0,0 +1,67 @@
+# [DEF:backend.tests.core.test_git_service_gitea_pr:Module]
+# @TIER: STANDARD
+# @SEMANTICS: tests, git, gitea, pull_request, fallback
+# @PURPOSE: Validate Gitea PR creation fallback behavior when configured server URL is stale.
+# @LAYER: Domain
+# @RELATION: TESTS -> backend.src.services.git_service.create_gitea_pull_request
+# @INVARIANT: A 404 from primary Gitea URL retries once against remote-url host when different.
+
+import asyncio
+import sys
+from pathlib import Path
+
+from fastapi import HTTPException
+
+sys.path.insert(0, str(Path(__file__).parent.parent.parent))
+
+from src.services.git_service import GitService
+
+
+# [DEF:test_derive_server_url_from_remote_strips_credentials:Function]
+# @PURPOSE: Ensure helper returns host base URL and removes embedded credentials.
+# @PRE: remote_url is an https URL with username/token.
+# @POST: Result is scheme+host only.
+def test_derive_server_url_from_remote_strips_credentials():
+    service = GitService(base_path="test_repos")
+    derived = service._derive_server_url_from_remote(
+        "https://oauth2:token@giteabusya.bebesh.ru/busya/covid-vaccine-dashboard.git"
+    )
+    assert derived == "https://giteabusya.bebesh.ru"
+# [/DEF:test_derive_server_url_from_remote_strips_credentials:Function]
+
+
+# [DEF:test_create_gitea_pull_request_retries_with_remote_host_on_404:Function]
+# @PURPOSE: Verify create_gitea_pull_request retries with remote URL host after primary 404.
+# @PRE: primary server_url differs from remote_url host.
+# @POST: Method returns success payload from fallback request.
+def test_create_gitea_pull_request_retries_with_remote_host_on_404(monkeypatch):
+    service = GitService(base_path="test_repos")
+    calls = []
+
+    async def fake_gitea_request(method, server_url, pat, endpoint, payload=None):
+        calls.append((method, server_url, endpoint))
+        if len(calls) == 1:
+            raise HTTPException(status_code=404, detail="Gitea API error: The target couldn't be found.")
+        return {"number": 42, "html_url": "https://giteabusya.bebesh.ru/busya/covid-vaccine-dashboard/pulls/42", "state": "open"}
+
+    monkeypatch.setattr(service, "_gitea_request", fake_gitea_request)
+
+    result = asyncio.run(
+        service.create_gitea_pull_request(
+            server_url="https://gitea.bebesh.ru",
+            pat="secret",
+            remote_url="https://oauth2:secret@giteabusya.bebesh.ru/busya/covid-vaccine-dashboard.git",
+            from_branch="ss-dev",
+            to_branch="main",
+            title="Promote ss-dev -> main",
+            description="",
+        )
+    )
+
+    assert result["id"] == 42
+    assert len(calls) == 2
+    assert calls[0][1] == "https://gitea.bebesh.ru"
+    assert calls[1][1] == "https://giteabusya.bebesh.ru"
+# [/DEF:test_create_gitea_pull_request_retries_with_remote_host_on_404:Function]
+
+# [/DEF:backend.tests.core.test_git_service_gitea_pr:Module]

backend/tests/fixtures/clean_release/fixtures_clean_release.json

@@ -0,0 +1,34 @@
+{
+  "policy_enterprise_clean": {
+    "policy_id": "policy-enterprise-clean-v1",
+    "policy_version": "1.0.0",
+    "active": true,
+    "prohibited_artifact_categories": ["test-data", "demo-data", "load-test", "sample-repository"],
+    "required_system_categories": ["system-init", "security-bootstrap", "schema-migrations"],
+    "external_source_forbidden": true,
+    "internal_source_registry_ref": "registry-internal-v1",
+    "effective_from": "2026-03-03T00:00:00Z",
+    "effective_to": null,
+    "profile": "enterprise-clean"
+  },
+  "candidate_clean_ready": {
+    "candidate_id": "2026.03.03-rc1",
+    "version": "2026.03.03",
+    "profile": "enterprise-clean",
+    "created_at": "2026-03-03T09:00:00Z",
+    "created_by": "release-manager",
+    "source_snapshot_ref": "git:abc123",
+    "status": "prepared"
+  },
+  "compliance_report_blocked_example": {
+    "report_id": "CCR-2026-03-03-001",
+    "check_run_id": "check-run-001",
+    "candidate_id": "2026.03.03-rc1",
+    "generated_at": "2026-03-03T09:15:00Z",
+    "final_status": "blocked",
+    "operator_summary": "Blocked due to external-source violation",
+    "structured_payload_ref": "file:///tmp/ccr-2026-03-03-001.json",
+    "violations_count": 2,
+    "blocking_violations_count": 2
+  }
+}

backend/tests/fixtures/migration_dry_run_fixture.json

@@ -0,0 +1,58 @@
+{
+  "source_dashboard_summary": [
+    {
+      "id": 42,
+      "title": "Sales"
+    }
+  ],
+  "target": {
+    "dashboards": [
+      {
+        "uuid": "dash-1",
+        "dashboard_title": "Sales Old",
+        "slug": "sales-old",
+        "position_json": "{}",
+        "json_metadata": "{}",
+        "description": "",
+        "owners": [
+          {
+            "username": "owner-a"
+          }
+        ]
+      }
+    ],
+    "datasets": [],
+    "charts": [],
+    "databases": []
+  },
+  "transformed_zip_objects": {
+    "dashboards": [
+      {
+        "uuid": "dash-1",
+        "title": "Sales New",
+        "signature": "{\"title\":\"Sales New\"}",
+        "owners": [
+          {
+            "username": "owner-b"
+          }
+        ]
+      }
+    ],
+    "charts": [
+      {
+        "uuid": "chart-1",
+        "title": "Chart A",
+        "signature": "{\"title\":\"Chart A\"}",
+        "dataset_uuid": "dataset-404"
+      }
+    ],
+    "datasets": [
+      {
+        "uuid": "dataset-1",
+        "title": "orders",
+        "signature": "{\"title\":\"orders\"}",
+        "database_uuid": "db-missing"
+      }
+    ]
+  }
+}

backend/tests/services/clean_release/test_manifest_builder.py

@@ -0,0 +1,41 @@
+# [DEF:backend.tests.services.clean_release.test_manifest_builder:Module]
+# @TIER: CRITICAL
+# @SEMANTICS: tests, clean-release, manifest, deterministic
+# @PURPOSE: Validate deterministic manifest generation behavior for US1.
+# @LAYER: Domain
+# @RELATION: VERIFIES -> backend.src.services.clean_release.manifest_builder
+# @INVARIANT: Same input artifacts produce identical deterministic hash.
+
+from src.services.clean_release.manifest_builder import build_distribution_manifest
+
+
+# [DEF:test_manifest_deterministic_hash_for_same_input:Function]
+# @PURPOSE: Ensure hash is stable for same candidate/policy/artifact input.
+# @PRE: Same input lists are passed twice.
+# @POST: Hash and summary remain identical.
+def test_manifest_deterministic_hash_for_same_input():
+    artifacts = [
+        {"path": "a.yaml", "category": "system-init", "classification": "required-system", "reason": "required"},
+        {"path": "b.yaml", "category": "test-data", "classification": "excluded-prohibited", "reason": "prohibited"},
+    ]
+
+    manifest1 = build_distribution_manifest(
+        manifest_id="m1",
+        candidate_id="2026.03.03-rc1",
+        policy_id="policy-enterprise-clean-v1",
+        generated_by="tester",
+        artifacts=artifacts,
+    )
+    manifest2 = build_distribution_manifest(
+        manifest_id="m2",
+        candidate_id="2026.03.03-rc1",
+        policy_id="policy-enterprise-clean-v1",
+        generated_by="tester",
+        artifacts=artifacts,
+    )
+
+    assert manifest1.deterministic_hash == manifest2.deterministic_hash
+    assert manifest1.summary.included_count == manifest2.summary.included_count
+    assert manifest1.summary.excluded_count == manifest2.summary.excluded_count
+# [/DEF:test_manifest_deterministic_hash_for_same_input:Function]
+# [/DEF:backend.tests.services.clean_release.test_manifest_builder:Module]

backend/tests/services/clean_release/test_policy_engine.py

@@ -0,0 +1,144 @@
+# [DEF:backend.tests.services.clean_release.test_policy_engine:Module]
+# @TIER: CRITICAL
+# @SEMANTICS: tests, clean-release, policy-engine, deterministic
+# @PURPOSE: Validate policy model contracts and deterministic classification prerequisites for US1.
+# @LAYER: Domain
+# @RELATION: VERIFIES -> backend.src.models.clean_release.CleanProfilePolicy
+# @INVARIANT: Enterprise policy rejects invalid activation states.
+
+import pytest
+from datetime import datetime, timezone
+
+from src.models.clean_release import CleanProfilePolicy, ProfileType
+
+
+# [DEF:test_policy_enterprise_clean_valid:Function]
+# @PURPOSE: Ensure valid enterprise policy payload is accepted.
+# @PRE: Fixture-like payload contains prohibited categories and registry ref.
+# @POST: Model is created with external_source_forbidden=True.
+def test_policy_enterprise_clean_valid():
+    policy = CleanProfilePolicy(
+        policy_id="policy-enterprise-clean-v1",
+        policy_version="1.0.0",
+        active=True,
+        prohibited_artifact_categories=["test-data", "demo-data"],
+        required_system_categories=["system-init"],
+        external_source_forbidden=True,
+        internal_source_registry_ref="registry-internal-v1",
+        effective_from=datetime.now(timezone.utc),
+        profile=ProfileType.ENTERPRISE_CLEAN,
+    )
+    assert policy.external_source_forbidden is True
+    assert policy.prohibited_artifact_categories == ["test-data", "demo-data"]
+# [/DEF:test_policy_enterprise_clean_valid:Function]
+
+
+# [DEF:test_policy_missing_registry_fails:Function]
+# @PURPOSE: Verify missing registry ref violates policy contract.
+# @PRE: enterprise-clean policy payload has blank registry ref.
+# @POST: Validation error is raised.
+def test_policy_missing_registry_fails():
+    with pytest.raises(ValueError):
+        CleanProfilePolicy(
+            policy_id="policy-enterprise-clean-v1",
+            policy_version="1.0.0",
+            active=True,
+            prohibited_artifact_categories=["test-data"],
+            required_system_categories=["system-init"],
+            external_source_forbidden=True,
+            internal_source_registry_ref="",
+            effective_from=datetime.now(timezone.utc),
+            profile=ProfileType.ENTERPRISE_CLEAN,
+        )
+# [/DEF:test_policy_missing_registry_fails:Function]
+
+
+# [DEF:test_policy_empty_prohibited_categories_fails:Function]
+# @PURPOSE: Verify enterprise policy cannot activate without prohibited categories.
+# @PRE: enterprise-clean policy payload has empty prohibited categories.
+# @POST: Validation error is raised.
+def test_policy_empty_prohibited_categories_fails():
+    with pytest.raises(ValueError):
+        CleanProfilePolicy(
+            policy_id="policy-enterprise-clean-v1",
+            policy_version="1.0.0",
+            active=True,
+            prohibited_artifact_categories=[],
+            required_system_categories=["system-init"],
+            external_source_forbidden=True,
+            internal_source_registry_ref="registry-internal-v1",
+            effective_from=datetime.now(timezone.utc),
+            profile=ProfileType.ENTERPRISE_CLEAN,
+        )
+# [/DEF:test_policy_empty_prohibited_categories_fails:Function]
+
+
+# [DEF:test_policy_conflicting_external_forbidden_flag_fails:Function]
+# @PURPOSE: Verify enterprise policy enforces external_source_forbidden=true.
+# @PRE: enterprise-clean policy payload sets external_source_forbidden to false.
+# @POST: Validation error is raised.
+def test_policy_conflicting_external_forbidden_flag_fails():
+    with pytest.raises(ValueError):
+        CleanProfilePolicy(
+            policy_id="policy-enterprise-clean-v1",
+            policy_version="1.0.0",
+            active=True,
+            prohibited_artifact_categories=["test-data"],
+            required_system_categories=["system-init"],
+            external_source_forbidden=False,
+            internal_source_registry_ref="registry-internal-v1",
+            effective_from=datetime.now(timezone.utc),
+            profile=ProfileType.ENTERPRISE_CLEAN,
+        )
+# [/DEF:test_policy_conflicting_external_forbidden_flag_fails:Function]
+# [/DEF:backend.tests.services.clean_release.test_policy_engine:Module]
+from src.models.clean_release import ResourceSourceRegistry, ResourceSourceEntry, RegistryStatus
+from src.services.clean_release.policy_engine import CleanPolicyEngine
+
+def _policy_enterprise_clean() -> CleanProfilePolicy:
+    return CleanProfilePolicy(
+        policy_id="policy-enterprise-clean-v1",
+        policy_version="1.0.0",
+        active=True,
+        prohibited_artifact_categories=["test-data"],
+        required_system_categories=["system-init"],
+        external_source_forbidden=True,
+        internal_source_registry_ref="registry-internal-v1",
+        effective_from=datetime.now(timezone.utc),
+        profile=ProfileType.ENTERPRISE_CLEAN,
+    )
+
+def _registry() -> ResourceSourceRegistry:
+    return ResourceSourceRegistry(
+        registry_id="registry-internal-v1",
+        name="Internal",
+        entries=[ResourceSourceEntry(source_id="1", host="nexus.internal", protocol="https", purpose="pkg", enabled=True)],
+        updated_at=datetime.now(timezone.utc),
+        updated_by="tester",
+    )
+
+# [DEF:test_policy_valid:Function]
+# @PURPOSE: Validate policy valid scenario
+def test_policy_valid():
+    engine = CleanPolicyEngine(_policy_enterprise_clean(), _registry())
+    res = engine.validate_policy()
+    assert res.ok is True
+
+# [DEF:test_conflicting_registry:Function]
+# @PURPOSE: Validate policy conflicting registry edge
+def test_conflicting_registry():
+    reg = _registry()
+    reg.registry_id = "other-registry"
+    engine = CleanPolicyEngine(_policy_enterprise_clean(), reg)
+    res = engine.validate_policy()
+    assert res.ok is False
+    assert "Policy registry ref does not match provided registry" in res.blocking_reasons
+
+# [DEF:test_external_endpoint:Function]
+# @PURPOSE: Validate policy external endpoint edge
+def test_external_endpoint():
+    engine = CleanPolicyEngine(_policy_enterprise_clean(), _registry())
+    res = engine.validate_resource_source("external.org")
+    assert res.ok is False
+    assert res.violation["category"] == "external-source"
+

backend/tests/services/clean_release/test_source_isolation.py

@@ -0,0 +1,58 @@
+# [DEF:backend.tests.services.clean_release.test_source_isolation:Module]
+# @TIER: STANDARD
+# @SEMANTICS: tests, clean-release, source-isolation, internal-only
+# @PURPOSE: Verify internal source registry validation behavior.
+# @LAYER: Domain
+# @RELATION: TESTS -> backend.src.services.clean_release.source_isolation
+# @INVARIANT: External endpoints always produce blocking violations.
+
+from datetime import datetime, timezone
+
+from src.models.clean_release import ResourceSourceEntry, ResourceSourceRegistry
+from src.services.clean_release.source_isolation import validate_internal_sources
+
+
+def _registry() -> ResourceSourceRegistry:
+    return ResourceSourceRegistry(
+        registry_id="registry-internal-v1",
+        name="Internal Sources",
+        entries=[
+            ResourceSourceEntry(
+                source_id="src-1",
+                host="repo.intra.company.local",
+                protocol="https",
+                purpose="artifact-repo",
+                enabled=True,
+            ),
+            ResourceSourceEntry(
+                source_id="src-2",
+                host="pypi.intra.company.local",
+                protocol="https",
+                purpose="package-mirror",
+                enabled=True,
+            ),
+        ],
+        updated_at=datetime.now(timezone.utc),
+        updated_by="tester",
+        status="active",
+    )
+
+
+def test_validate_internal_sources_all_internal_ok():
+    result = validate_internal_sources(
+        registry=_registry(),
+        endpoints=["repo.intra.company.local", "pypi.intra.company.local"],
+    )
+    assert result["ok"] is True
+    assert result["violations"] == []
+
+
+def test_validate_internal_sources_external_blocked():
+    result = validate_internal_sources(
+        registry=_registry(),
+        endpoints=["repo.intra.company.local", "pypi.org"],
+    )
+    assert result["ok"] is False
+    assert len(result["violations"]) == 1
+    assert result["violations"][0]["category"] == "external-source"
+    assert result["violations"][0]["blocked_release"] is True

backend/tests/test_dashboards_api.py

@@ -1,73 +1,366 @@
 # [DEF:backend.tests.test_dashboards_api:Module]
 # @TIER: STANDARD
-# @PURPOSE: Contract-driven tests for Dashboard Hub API
+# @PURPOSE: Comprehensive contract-driven tests for Dashboard Hub API
 # @LAYER: Domain (Tests)
-# @SEMANTICS: tests, dashboards, api, contract
-# @RELATION: TESTS -> backend.src.api.routes.dashboards
-
+# @SEMANTICS: tests, dashboards, api, contract, remediation
+import pytest
 from fastapi.testclient import TestClient
-from unittest.mock import MagicMock, patch
+from unittest.mock import MagicMock, patch, AsyncMock
+from datetime import datetime, timezone
 from src.app import app
-from src.api.routes.dashboards import DashboardsResponse
+from src.api.routes.dashboards import DashboardsResponse, DashboardDetailResponse, DashboardTaskHistoryResponse, DatabaseMappingsResponse
+from src.dependencies import get_current_user, has_permission, get_config_manager, get_task_manager, get_resource_service, get_mapping_service
 
+# Global mock user
+mock_user = MagicMock()
+mock_user.username = "testuser"
+mock_user.roles = []
+admin_role = MagicMock()
+admin_role.name = "Admin"
+mock_user.roles.append(admin_role)
+
+@pytest.fixture(autouse=True)
+def mock_deps():
+    config_manager = MagicMock()
+    task_manager = MagicMock()
+    resource_service = MagicMock()
+    mapping_service = MagicMock()
+    
+    app.dependency_overrides[get_config_manager] = lambda: config_manager
+    app.dependency_overrides[get_task_manager] = lambda: task_manager
+    app.dependency_overrides[get_resource_service] = lambda: resource_service
+    app.dependency_overrides[get_mapping_service] = lambda: mapping_service
+    app.dependency_overrides[get_current_user] = lambda: mock_user
+    
+    # Overrides for specific permission checks
+    app.dependency_overrides[has_permission("plugin:migration", "READ")] = lambda: mock_user
+    app.dependency_overrides[has_permission("plugin:migration", "EXECUTE")] = lambda: mock_user
+    app.dependency_overrides[has_permission("plugin:backup", "EXECUTE")] = lambda: mock_user
+    app.dependency_overrides[has_permission("tasks", "READ")] = lambda: mock_user
+    app.dependency_overrides[has_permission("dashboards", "READ")] = lambda: mock_user
+    
+    yield {
+        "config": config_manager,
+        "task": task_manager,
+        "resource": resource_service,
+        "mapping": mapping_service
+    }
+    app.dependency_overrides.clear()
+    
 client = TestClient(app)
 
-# [DEF:test_get_dashboards_success:Function]
-# @TEST: GET /api/dashboards returns 200 and valid schema
-# @PRE: env_id exists
-# @POST: Response matches DashboardsResponse schema
-def test_get_dashboards_success():
-    with patch("src.api.routes.dashboards.get_config_manager") as mock_config, \
-         patch("src.api.routes.dashboards.get_resource_service") as mock_service, \
-         patch("src.api.routes.dashboards.has_permission") as mock_perm:
+# --- 1. get_dashboards tests ---
+
+def test_get_dashboards_success(mock_deps):
+    """Uses @TEST_FIXTURE: dashboard_list_happy data."""
+    mock_env = MagicMock()
+    mock_env.id = "prod"
+    mock_deps["config"].get_environments.return_value = [mock_env]
+    mock_deps["task"].get_all_tasks.return_value = []
+    
+    # @TEST_FIXTURE: dashboard_list_happy -> {"id": 1, "title": "Main Revenue"}
+    mock_deps["resource"].get_dashboards_with_status = AsyncMock(return_value=[
+        {"id": 1, "title": "Main Revenue", "slug": "main-revenue", "git_status": {"branch": "main", "sync_status": "OK"}}
+    ])
+
+    response = client.get("/api/dashboards?env_id=prod&page=1&page_size=10")
+    
+    assert response.status_code == 200
+    data = response.json()
+    
+    # exhaustive @POST assertions
+    assert "dashboards" in data
+    assert len(data["dashboards"]) == 1  # @TEST_FIXTURE: expected_count: 1
+    assert data["dashboards"][0]["title"] == "Main Revenue"
+    assert data["total"] == 1
+    assert data["page"] == 1
+    assert data["page_size"] == 10
+    assert data["total_pages"] == 1
+    
+    # schema validation
+    DashboardsResponse(**data)
+
+def test_get_dashboards_with_search(mock_deps):
+    mock_env = MagicMock()
+    mock_env.id = "prod"
+    mock_deps["config"].get_environments.return_value = [mock_env]
+    mock_deps["task"].get_all_tasks.return_value = []
+    mock_deps["resource"].get_dashboards_with_status = AsyncMock(return_value=[
+        {"id": 1, "title": "Sales Report", "slug": "sales"},
+        {"id": 2, "title": "Marketing", "slug": "marketing"}
+    ])
         
-        # Mock environment
+    response = client.get("/api/dashboards?env_id=prod&search=sales")
+    assert response.status_code == 200
+    data = response.json()
+    assert len(data["dashboards"]) == 1
+    assert data["dashboards"][0]["title"] == "Sales Report"
+
+def test_get_dashboards_empty(mock_deps):
+    """@TEST_EDGE: empty_dashboards -> {env_id: 'empty_env', expected_total: 0}"""
+    mock_env = MagicMock()
+    mock_env.id = "empty_env"
+    mock_deps["config"].get_environments.return_value = [mock_env]
+    mock_deps["task"].get_all_tasks.return_value = []
+    mock_deps["resource"].get_dashboards_with_status = AsyncMock(return_value=[])
+    
+    response = client.get("/api/dashboards?env_id=empty_env")
+    assert response.status_code == 200
+    data = response.json()
+    assert data["total"] == 0
+    assert len(data["dashboards"]) == 0
+    assert data["total_pages"] == 1
+    DashboardsResponse(**data)
+
+def test_get_dashboards_superset_failure(mock_deps):
+    """@TEST_EDGE: external_superset_failure -> {env_id: 'bad_conn', status: 503}"""
+    mock_env = MagicMock()
+    mock_env.id = "bad_conn"
+    mock_deps["config"].get_environments.return_value = [mock_env]
+    mock_deps["task"].get_all_tasks.return_value = []
+    mock_deps["resource"].get_dashboards_with_status = AsyncMock(
+        side_effect=Exception("Connection refused")
+    )
+    
+    response = client.get("/api/dashboards?env_id=bad_conn")
+    assert response.status_code == 503
+    assert "Failed to fetch dashboards" in response.json()["detail"]
+
+def test_get_dashboards_env_not_found(mock_deps):
+    mock_deps["config"].get_environments.return_value = []
+    response = client.get("/api/dashboards?env_id=nonexistent")
+    assert response.status_code == 404
+    assert "Environment not found" in response.json()["detail"]
+
+def test_get_dashboards_invalid_pagination(mock_deps):
+    mock_env = MagicMock()
+    mock_env.id = "prod"
+    mock_deps["config"].get_environments.return_value = [mock_env]
+    
+    # page < 1
+    assert client.get("/api/dashboards?env_id=prod&page=0").status_code == 400
+    assert client.get("/api/dashboards?env_id=prod&page=-1").status_code == 400
+    
+    # page_size < 1
+    assert client.get("/api/dashboards?env_id=prod&page_size=0").status_code == 400
+    
+    # page_size > 100
+    assert client.get("/api/dashboards?env_id=prod&page_size=101").status_code == 400
+
+# --- 2. get_database_mappings tests ---
+
+def test_get_database_mappings_success(mock_deps):
+    mock_s = MagicMock(); mock_s.id = "s"
+    mock_t = MagicMock(); mock_t.id = "t"
+    mock_deps["config"].get_environments.return_value = [mock_s, mock_t]
+    
+    mock_deps["mapping"].get_suggestions = AsyncMock(return_value=[
+        {"source_db": "src", "target_db": "dst", "confidence": 0.9}
+    ])
+    response = client.get("/api/dashboards/db-mappings?source_env_id=s&target_env_id=t")
+    assert response.status_code == 200
+    data = response.json()
+    assert len(data["mappings"]) == 1
+    assert data["mappings"][0]["confidence"] == 0.9
+    DatabaseMappingsResponse(**data)
+
+def test_get_database_mappings_env_not_found(mock_deps):
+    mock_deps["config"].get_environments.return_value = []
+    response = client.get("/api/dashboards/db-mappings?source_env_id=ghost&target_env_id=t")
+    assert response.status_code == 404
+
+# --- 3. get_dashboard_detail tests ---
+
+def test_get_dashboard_detail_success(mock_deps):
+    with patch("src.api.routes.dashboards.SupersetClient") as mock_client_cls:
         mock_env = MagicMock()
         mock_env.id = "prod"
-        mock_config.return_value.get_environments.return_value = [mock_env]
+        mock_deps["config"].get_environments.return_value = [mock_env]
         
-        # Mock resource service response
-        mock_service.return_value.get_dashboards_with_status.return_value = [
-            {
-                "id": 1,
-                "title": "Sales Report",
-                "slug": "sales",
-                "git_status": {"branch": "main", "sync_status": "OK"},
-                "last_task": {"task_id": "task-1", "status": "SUCCESS"}
-            }
-        ]
-        
-        # Mock permission
-        mock_perm.return_value = lambda: True
+        mock_client = MagicMock()
+        detail_payload = {
+            "id": 42, "title": "Detail", "charts": [], "datasets": [],
+            "chart_count": 0, "dataset_count": 0
+        }
+        mock_client.get_dashboard_detail.return_value = detail_payload
+        mock_client_cls.return_value = mock_client
 
-        response = client.get("/api/dashboards?env_id=prod")
-        
+        response = client.get("/api/dashboards/42?env_id=prod")
         assert response.status_code == 200
         data = response.json()
-        assert "dashboards" in data
-        assert len(data["dashboards"]) == 1
-        assert data["dashboards"][0]["title"] == "Sales Report"
-        # Validate against Pydantic model
-        DashboardsResponse(**data)
+        assert data["id"] == 42
+        DashboardDetailResponse(**data)
 
-# [/DEF:test_get_dashboards_success:Function]
+def test_get_dashboard_detail_env_not_found(mock_deps):
+    mock_deps["config"].get_environments.return_value = []
+    response = client.get("/api/dashboards/42?env_id=missing")
+    assert response.status_code == 404
 
-# [DEF:test_get_dashboards_env_not_found:Function]
-# @TEST: GET /api/dashboards returns 404 if env_id missing
-# @PRE: env_id does not exist
-# @POST: Returns 404 error
-def test_get_dashboards_env_not_found():
-    with patch("src.api.routes.dashboards.get_config_manager") as mock_config, \
-         patch("src.api.routes.dashboards.has_permission") as mock_perm:
+# --- 4. get_dashboard_tasks_history tests ---
+
+def test_get_dashboard_tasks_history_success(mock_deps):
+    now = datetime.now(timezone.utc)
+    task1 = MagicMock(id="t1", plugin_id="superset-backup", status="SUCCESS", started_at=now, finished_at=None, params={"env": "prod", "dashboards": [42]}, result={})
+    mock_deps["task"].get_all_tasks.return_value = [task1]
+
+    response = client.get("/api/dashboards/42/tasks?env_id=prod")
+    assert response.status_code == 200
+    data = response.json()
+    assert data["dashboard_id"] == 42
+    assert len(data["items"]) == 1
+    DashboardTaskHistoryResponse(**data)
+
+def test_get_dashboard_tasks_history_sorting(mock_deps):
+    """@POST: Response contains sorted task history (newest first)."""
+    from datetime import timedelta
+    now = datetime.now(timezone.utc)
+    older = now - timedelta(hours=2)
+    newest = now
+    
+    task_old = MagicMock(id="t-old", plugin_id="superset-backup", status="SUCCESS",
+                         started_at=older, finished_at=None,
+                         params={"env": "prod", "dashboards": [42]}, result={})
+    task_new = MagicMock(id="t-new", plugin_id="superset-backup", status="RUNNING",
+                         started_at=newest, finished_at=None,
+                         params={"env": "prod", "dashboards": [42]}, result={})
+    
+    # Provide in wrong order to verify the endpoint sorts
+    mock_deps["task"].get_all_tasks.return_value = [task_old, task_new]
+
+    response = client.get("/api/dashboards/42/tasks?env_id=prod")
+    assert response.status_code == 200
+    data = response.json()
+    assert len(data["items"]) == 2
+    # Newest first
+    assert data["items"][0]["id"] == "t-new"
+    assert data["items"][1]["id"] == "t-old"
+
+# --- 5. get_dashboard_thumbnail tests ---
+
+def test_get_dashboard_thumbnail_success(mock_deps):
+    with patch("src.api.routes.dashboards.SupersetClient") as mock_client_cls:
+        mock_env = MagicMock(); mock_env.id = "prod"
+        mock_deps["config"].get_environments.return_value = [mock_env]
+        mock_client = MagicMock()
+        mock_response = MagicMock(status_code=200, content=b"img", headers={"Content-Type": "image/png"})
+        mock_client.network.request.side_effect = lambda method, endpoint, **kw: {"image_url": "url"} if method == "POST" else mock_response
+        mock_client_cls.return_value = mock_client
+
+        response = client.get("/api/dashboards/42/thumbnail?env_id=prod")
+        assert response.status_code == 200
+        assert response.content == b"img"
+
+def test_get_dashboard_thumbnail_env_not_found(mock_deps):
+    mock_deps["config"].get_environments.return_value = []
+    response = client.get("/api/dashboards/42/thumbnail?env_id=missing")
+    assert response.status_code == 404
+
+def test_get_dashboard_thumbnail_202(mock_deps):
+    """@POST: Returns 202 when thumbnail is being prepared by Superset."""
+    with patch("src.api.routes.dashboards.SupersetClient") as mock_client_cls:
+        mock_env = MagicMock(); mock_env.id = "prod"
+        mock_deps["config"].get_environments.return_value = [mock_env]
+        mock_client = MagicMock()
         
-        mock_config.return_value.get_environments.return_value = []
-        mock_perm.return_value = lambda: True
+        # POST cache_dashboard_screenshot returns image_url
+        mock_client.network.request.side_effect = [
+            {"image_url": "/api/v1/dashboard/42/thumbnail/abc123/"},  # POST
+            MagicMock(status_code=202, json=lambda: {"message": "Thumbnail is being generated"},
+                      headers={"Content-Type": "application/json"})  # GET thumbnail -> 202
+        ]
+        mock_client_cls.return_value = mock_client
 
-        response = client.get("/api/dashboards?env_id=nonexistent")
-        
-        assert response.status_code == 404
-        assert "Environment not found" in response.json()["detail"]
+        response = client.get("/api/dashboards/42/thumbnail?env_id=prod")
+        assert response.status_code == 202
+        assert "Thumbnail is being generated" in response.json()["message"]
 
-# [/DEF:test_get_dashboards_env_not_found:Function]
+# --- 6. migrate_dashboards tests ---
+
+def test_migrate_dashboards_success(mock_deps):
+    mock_s = MagicMock(); mock_s.id = "s"
+    mock_t = MagicMock(); mock_t.id = "t"
+    mock_deps["config"].get_environments.return_value = [mock_s, mock_t]
+    mock_deps["task"].create_task = AsyncMock(return_value=MagicMock(id="task-123"))
+
+    response = client.post("/api/dashboards/migrate", json={
+        "source_env_id": "s", "target_env_id": "t", "dashboard_ids": [1]
+    })
+    assert response.status_code == 200
+    assert response.json()["task_id"] == "task-123"
+
+def test_migrate_dashboards_pre_checks(mock_deps):
+    # Missing IDs
+    response = client.post("/api/dashboards/migrate", json={
+        "source_env_id": "s", "target_env_id": "t", "dashboard_ids": []
+    })
+    assert response.status_code == 400
+    assert "At least one dashboard ID must be provided" in response.json()["detail"]
+
+def test_migrate_dashboards_env_not_found(mock_deps):
+    """@PRE: source_env_id and target_env_id are valid environment IDs."""
+    mock_deps["config"].get_environments.return_value = []
+    response = client.post("/api/dashboards/migrate", json={
+        "source_env_id": "ghost", "target_env_id": "t", "dashboard_ids": [1]
+    })
+    assert response.status_code == 404
+    assert "Source environment not found" in response.json()["detail"]
+
+# --- 7. backup_dashboards tests ---
+
+def test_backup_dashboards_success(mock_deps):
+    mock_env = MagicMock(); mock_env.id = "prod"
+    mock_deps["config"].get_environments.return_value = [mock_env]
+    mock_deps["task"].create_task = AsyncMock(return_value=MagicMock(id="backup-123"))
+
+    response = client.post("/api/dashboards/backup", json={
+        "env_id": "prod", "dashboard_ids": [1]
+    })
+    assert response.status_code == 200
+    assert response.json()["task_id"] == "backup-123"
+
+def test_backup_dashboards_pre_checks(mock_deps):
+    response = client.post("/api/dashboards/backup", json={
+        "env_id": "prod", "dashboard_ids": []
+    })
+    assert response.status_code == 400
+
+def test_backup_dashboards_env_not_found(mock_deps):
+    """@PRE: env_id is a valid environment ID."""
+    mock_deps["config"].get_environments.return_value = []
+    response = client.post("/api/dashboards/backup", json={
+        "env_id": "ghost", "dashboard_ids": [1]
+    })
+    assert response.status_code == 404
+    assert "Environment not found" in response.json()["detail"]
+
+def test_backup_dashboards_with_schedule(mock_deps):
+    """@POST: If schedule is provided, a scheduled task is created."""
+    mock_env = MagicMock(); mock_env.id = "prod"
+    mock_deps["config"].get_environments.return_value = [mock_env]
+    mock_deps["task"].create_task = AsyncMock(return_value=MagicMock(id="sched-456"))
+
+    response = client.post("/api/dashboards/backup", json={
+        "env_id": "prod", "dashboard_ids": [1], "schedule": "0 0 * * *"
+    })
+    assert response.status_code == 200
+    assert response.json()["task_id"] == "sched-456"
+    
+    # Verify schedule was propagated to create_task
+    call_kwargs = mock_deps["task"].create_task.call_args
+    task_params = call_kwargs.kwargs.get("params") or call_kwargs[1].get("params", {})
+    assert task_params["schedule"] == "0 0 * * *"
+
+# --- 8. Internal logic: _task_matches_dashboard ---
+from src.api.routes.dashboards import _task_matches_dashboard
+
+def test_task_matches_dashboard_logic():
+    task = MagicMock(plugin_id="superset-backup", params={"dashboards": [42], "env": "prod"})
+    assert _task_matches_dashboard(task, 42, "prod") is True
+    assert _task_matches_dashboard(task, 43, "prod") is False
+    assert _task_matches_dashboard(task, 42, "dev") is False
+
+    llm_task = MagicMock(plugin_id="llm_dashboard_validation", params={"dashboard_id": 42, "environment_id": "prod"})
+    assert _task_matches_dashboard(llm_task, 42, "prod") is True
+    assert _task_matches_dashboard(llm_task, 42, None) is True
 
 # [/DEF:backend.tests.test_dashboards_api:Module]

backend/tests/test_logger.py

@@ -1,3 +1,11 @@
+# [DEF:tests.test_logger:Module]
+# @TIER: STANDARD
+# @SEMANTICS: logging, tests, belief_state
+# @PURPOSE: Unit tests for the custom logger formatters and configuration context manager.
+# @LAYER: Logging (Tests)
+# @RELATION: VERIFIES -> src/core/logger.py
+# @INVARIANT: All required log statements must correctly check the threshold.
+
 import pytest
 from src.core.logger import (
     belief_scope,
@@ -210,4 +218,5 @@ def test_enable_belief_state_flag(caplog):
         enable_belief_state=True
     )
     configure_logger(config)
-# [/DEF:test_enable_belief_state_flag:Function]
+# [/DEF:test_enable_belief_state_flag:Function]
+# [/DEF:tests.test_logger:Module]

backend/tests/test_resource_hubs.py

@@ -1,6 +1,6 @@
 import pytest
 from fastapi.testclient import TestClient
-from unittest.mock import MagicMock
+from unittest.mock import MagicMock, AsyncMock
 from src.app import app
 from src.dependencies import get_config_manager, get_task_manager, get_resource_service, has_permission
 
@@ -27,10 +27,10 @@ def mock_deps():
     task_manager.get_all_tasks.return_value = []
     
     # Mock dashboards
-    resource_service.get_dashboards_with_status.return_value = [
+    resource_service.get_dashboards_with_status = AsyncMock(return_value=[
         {"id": 1, "title": "Sales", "slug": "sales", "git_status": {"branch": "main", "sync_status": "OK"}, "last_task": None},
         {"id": 2, "title": "Marketing", "slug": "mkt", "git_status": None, "last_task": {"task_id": "t1", "status": "SUCCESS"}}
-    ]
+    ])
     
     app.dependency_overrides[get_config_manager] = lambda: config_manager
     app.dependency_overrides[get_task_manager] = lambda: task_manager
@@ -39,6 +39,10 @@ def mock_deps():
     # Bypass permission check
     mock_user = MagicMock()
     mock_user.username = "testadmin"
+    mock_user.roles = []
+    admin_role = MagicMock()
+    admin_role.name = "Admin"
+    mock_user.roles.append(admin_role)
     
     # Override both get_current_user and has_permission
     from src.dependencies import get_current_user
@@ -85,9 +89,9 @@ def test_get_dashboards_search(mock_deps):
 # @TEST: Negative - Service failure returns 503
 
 def test_get_datasets_success(mock_deps):
-    mock_deps["resource"].get_datasets_with_status.return_value = [
+    mock_deps["resource"].get_datasets_with_status = AsyncMock(return_value=[
         {"id": 1, "table_name": "orders", "schema": "public", "database": "db1", "mapped_fields": {"total": 10, "mapped": 5}, "last_task": None}
-    ]
+    ])
     
     response = client.get("/api/datasets?env_id=env1")
     assert response.status_code == 200
@@ -102,10 +106,10 @@ def test_get_datasets_not_found(mock_deps):
     assert response.status_code == 404
 
 def test_get_datasets_search(mock_deps):
-    mock_deps["resource"].get_datasets_with_status.return_value = [
+    mock_deps["resource"].get_datasets_with_status = AsyncMock(return_value=[
         {"id": 1, "table_name": "orders", "schema": "public", "database": "db1", "mapped_fields": {"total": 10, "mapped": 5}, "last_task": None},
         {"id": 2, "table_name": "users", "schema": "public", "database": "db1", "mapped_fields": {"total": 5, "mapped": 5}, "last_task": None}
-    ]
+    ])
     
     response = client.get("/api/datasets?env_id=env1&search=orders")
     assert response.status_code == 200
@@ -114,10 +118,39 @@ def test_get_datasets_search(mock_deps):
     assert data["datasets"][0]["table_name"] == "orders"
 
 def test_get_datasets_service_failure(mock_deps):
-    mock_deps["resource"].get_datasets_with_status.side_effect = Exception("Superset down")
+    mock_deps["resource"].get_datasets_with_status = AsyncMock(side_effect=Exception("Superset down"))
     
     response = client.get("/api/datasets?env_id=env1")
     assert response.status_code == 503
     assert "Failed to fetch datasets" in response.json()["detail"]
 
 # [/DEF:test_datasets_api:Test]
+
+
+# [DEF:test_pagination_boundaries:Test]
+# @PURPOSE: Verify pagination validation for GET endpoints
+# @TEST: page<1 and page_size>100 return 400
+
+def test_get_dashboards_pagination_zero_page(mock_deps):
+    """@TEST_EDGE: pagination_zero_page -> {page:0, status:400}"""
+    response = client.get("/api/dashboards?env_id=env1&page=0")
+    assert response.status_code == 400
+    assert "Page must be >= 1" in response.json()["detail"]
+
+def test_get_dashboards_pagination_oversize(mock_deps):
+    """@TEST_EDGE: pagination_oversize -> {page_size:101, status:400}"""
+    response = client.get("/api/dashboards?env_id=env1&page_size=101")
+    assert response.status_code == 400
+    assert "Page size must be between 1 and 100" in response.json()["detail"]
+
+def test_get_datasets_pagination_zero_page(mock_deps):
+    """@TEST_EDGE: pagination_zero_page on datasets"""
+    response = client.get("/api/datasets?env_id=env1&page=0")
+    assert response.status_code == 400
+
+def test_get_datasets_pagination_oversize(mock_deps):
+    """@TEST_EDGE: pagination_oversize on datasets"""
+    response = client.get("/api/datasets?env_id=env1&page_size=101")
+    assert response.status_code == 400
+
+# [/DEF:test_pagination_boundaries:Test]