tasks and workflow updated

.kilocode/workflows/speckit.analyze.md

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

.kilocode/workflows/speckit.implement.md

@@ -46,6 +46,7 @@ You **MUST** consider the user input before proceeding (if not empty).
      - Automatically proceed to step 3
 
 3. Load and analyze the implementation context:
+   - **REQUIRED**: Read `semantic_protocol.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
@@ -111,6 +112,7 @@ 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 `semantic_protocol.md` rules - every file must start with [DEF] header, include @TIER, and define contracts
    - **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

.kilocode/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 `.specify/memory/constitution.md`. Load IMPL_PLAN template (already copied).
+2. **Load context**: Read FEATURE_SPEC, `semantic_protocol.md` and `.specify/memory/constitution.md`. Load IMPL_PLAN template (already copied).
 
 3. **Execute plan workflow**: Follow the structure in IMPL_PLAN template to:
    - Fill Technical Context (mark unknowns as "NEEDS CLARIFICATION")
@@ -69,7 +69,13 @@ You **MUST** consider the user input before proceeding (if not empty).
    - Validation rules from requirements
    - State transitions if applicable
 
-2. **Generate API contracts** from functional requirements:
+2. **Define Module & Function Contracts (Semantic Protocol)**:
+   - **MANDATORY**: For every new module, define the [DEF] Header and Module-level Contract (@TIER, @PURPOSE, @INVARIANT) as per `semantic_protocol.md`.
+   - **REQUIRED**: Define Function Contracts (@PRE, @POST) for critical logic.
+   - Output specific contract definitions to `contracts/modules.md` or append to `data-model.md` to guide implementation.
+   - Ensure strict adherence to `semantic_protocol.md` syntax.
+
+3. **Generate API contracts** from functional requirements:
    - For each user action → endpoint
    - Use standard REST/GraphQL patterns
    - Output OpenAPI/GraphQL schema to `/contracts/`

.kilocodemodes

@@ -13,20 +13,6 @@ customModes:
       - browser
       - mcp
     customInstructions: 1. Always begin by loading the relevant plan or task list from the `specs/` directory. 2. Do not assume a task is done just because it is checked; verify the code or functionality first if asked to audit. 3. When updating task lists, ensure you only mark items as complete if you have verified them.
-  - slug: product-manager
-    name: Product Manager
-    description: Executes SpecKit workflows for feature management
-    roleDefinition: |-
-      You are Kilo Code, acting as a Product Manager. Your purpose is to rigorously execute the workflows defined in `.kilocode/workflows/`.
-      You act as the orchestrator for: - Specification (`speckit.specify`, `speckit.clarify`) - Planning (`speckit.plan`) - Task Management (`speckit.tasks`, `speckit.taskstoissues`) - Quality Assurance (`speckit.analyze`, `speckit.checklist`) - Governance (`speckit.constitution`) - Implementation Oversight (`speckit.implement`)
-      For each task, you must read the relevant workflow file from `.kilocode/workflows/` and follow its Execution Steps precisely.
-    whenToUse: Use this mode when you need to run any /speckit.* command or when dealing with high-level feature planning, specification writing, or project management tasks.
-    groups:
-      - read
-      - edit
-      - command
-      - mcp
-    customInstructions: 1. Always read the specific workflow file in `.kilocode/workflows/` before executing a command. 2. Adhere strictly to the "Operating Constraints" and "Execution Steps" in the workflow files.
   - slug: semantic
     name: Semantic Agent
     roleDefinition: |-
@@ -43,3 +29,18 @@ customModes:
       - browser
       - mcp
     source: project
+  - slug: product-manager
+    name: Product Manager
+    roleDefinition: |-
+      Your purpose is to rigorously execute the workflows defined in `.kilocode/workflows/`.
+      You act as the orchestrator for: - Specification (`speckit.specify`, `speckit.clarify`) - Planning (`speckit.plan`) - Task Management (`speckit.tasks`, `speckit.taskstoissues`) - Quality Assurance (`speckit.analyze`, `speckit.checklist`) - Governance (`speckit.constitution`) - Implementation Oversight (`speckit.implement`)
+      For each task, you must read the relevant workflow file from `.kilocode/workflows/` and follow its Execution Steps precisely.
+    whenToUse: Use this mode when you need to run any /speckit.* command or when dealing with high-level feature planning, specification writing, or project management tasks.
+    description: Executes SpecKit workflows for feature management
+    customInstructions: 1. Always read the specific workflow file in `.kilocode/workflows/` before executing a command. 2. Adhere strictly to the "Operating Constraints" and "Execution Steps" in the workflow files.
+    groups:
+      - read
+      - edit
+      - command
+      - mcp
+    source: project

.specify/templates/tasks-arch-template.md

@@ -1,35 +0,0 @@
----
-
-description: "Architecture task list template (Contracts & Scaffolding)"
----
-
-# Architecture Tasks: [FEATURE NAME]
-
-**Role**: Architect Agent
-**Goal**: Define the "What" and "Why" (Contracts, Scaffolding, Models) before implementation.
-**Input**: Design documents from `/specs/[###-feature-name]/`
-**Output**: Files with `[DEF]` anchors, `@PRE`/`@POST` contracts, and `@RELATION` mappings. No business logic.
-
-## Phase 1: Setup & Models
-
-- [ ] A001 Create/Update data models in [path] with `[DEF]` and contracts
-- [ ] A002 Define API route structure/contracts in [path]
-- [ ] A003 Define shared utilities/interfaces
-
-## Phase 2: User Story 1 - [Title]
-
-- [ ] A004 [US1] Define contracts for [Component/Service] in [path]
-- [ ] A005 [US1] Define contracts for [Endpoint] in [path]
-- [ ] A006 [US1] Define contracts for [Frontend Component] in [path]
-
-## Phase 3: User Story 2 - [Title]
-
-- [ ] A007 [US2] Define contracts for [Component/Service] in [path]
-- [ ] A008 [US2] Define contracts for [Endpoint] in [path]
-
-## Handover Checklist
-
-- [ ] All new files created with `[DEF]` anchors
-- [ ] All functions/classes have `@PURPOSE`, `@PRE`, `@POST` tags
-- [ ] No "naked code" (logic outside of anchors)
-- [ ] `tasks-dev.md` is ready for the Developer Agent

.specify/templates/tasks-dev-template.md

@@ -1,35 +0,0 @@
----
-
-description: "Developer task list template (Implementation Logic)"
----
-
-# Developer Tasks: [FEATURE NAME]
-
-**Role**: Developer Agent
-**Goal**: Implement the "How" (Logic, State, Error Handling) inside the defined contracts.
-**Input**: `tasks-arch.md` (completed), Scaffolding files with `[DEF]` anchors.
-**Output**: Working code that satisfies `@PRE`/`@POST` conditions.
-
-## Phase 1: Setup & Models
-
-- [ ] D001 Implement logic for [Model] in [path]
-- [ ] D002 Implement logic for [API Route] in [path]
-- [ ] D003 Implement shared utilities
-
-## Phase 2: User Story 1 - [Title]
-
-- [ ] D004 [US1] Implement logic for [Component/Service] in [path]
-- [ ] D005 [US1] Implement logic for [Endpoint] in [path]
-- [ ] D006 [US1] Implement logic for [Frontend Component] in [path]
-- [ ] D007 [US1] Verify semantic compliance and belief state logging
-
-## Phase 3: User Story 2 - [Title]
-
-- [ ] D008 [US2] Implement logic for [Component/Service] in [path]
-- [ ] D009 [US2] Implement logic for [Endpoint] in [path]
-
-## Polish & Quality Assurance
-
-- [ ] DXXX Verify all tests pass
-- [ ] DXXX Check error handling and edge cases
-- [ ] DXXX Ensure code style compliance

specs/017-llm-analysis-plugin/checklists/data-integrity.md

@@ -5,14 +5,14 @@
 **Created**: 2026-01-28
 
 ## Requirement Completeness
-- [ ] CHK001 Are requirements defined for mapping generated documentation to the correct metadata fields? [Completeness, Spec §FR-017]
+- [x] CHK001 Are requirements defined for mapping generated documentation to the correct metadata fields? [Completeness, Spec §FR-017]
 - [ ] CHK002 Are requirements specified for handling schema changes during documentation generation? [Completeness, Gap]
 - [ ] CHK003 Are requirements defined for validating the format of the generated commit message? [Completeness, Gap]
 - [ ] CHK004 Are requirements specified for concurrent documentation updates? [Completeness, Gap]
 
 ## Requirement Clarity
 - [ ] CHK005 Is "structured description" defined with specific markdown or text constraints? [Clarity, Spec §SC-004]
-- [ ] CHK006 Are "recent commit history" requirements defined by count or time window? [Clarity, Spec §FR-012]
+- [x] CHK006 Are "recent commit history" requirements defined by count or time window? [Clarity, Spec §FR-012]
 
 ## Edge Case Coverage
 - [ ] CHK007 Are requirements defined for when the LLM generates hallucinated column names? [Edge Case, Gap]

specs/017-llm-analysis-plugin/checklists/reliability-security.md

@@ -5,12 +5,12 @@
 **Created**: 2026-01-28
 
 ## Requirement Completeness
-- [ ] CHK001 Are retry strategies (count, backoff) defined for all external LLM API calls? [Completeness, Spec §FR-018]
+- [x] CHK001 Are retry strategies (count, backoff) defined for all external LLM API calls? [Completeness, Spec §FR-018]
-- [ ] CHK002 Are timeout thresholds specified for long-running validation tasks? [Completeness, Gap]
+- [x] CHK002 Are timeout thresholds specified for long-running validation tasks? [Completeness, Gap]
-- [ ] CHK003 Are encryption requirements defined for storing API keys at rest? [Completeness, Spec §FR-002]
+- [x] CHK003 Are encryption requirements defined for storing API keys at rest? [Completeness, Spec §FR-002]
 - [ ] CHK004 Are masking requirements defined for displaying API keys in the UI? [Completeness, Gap]
-- [ ] CHK005 Is the fallback behavior defined when the primary screenshot method (Headless) fails? [Completeness, Spec §FR-016]
+- [x] CHK005 Is the fallback behavior defined when the primary screenshot method (Headless) fails? [Completeness, Spec §FR-016]
-- [ ] CHK006 Are requirements defined for handling rate limits from LLM providers? [Completeness, Gap]
+- [x] CHK006 Are requirements defined for handling rate limits from LLM providers? [Completeness, Gap]
 - [ ] CHK007 Are data privacy requirements specified regarding what dashboard data (screenshots, logs) is sent to the LLM? [Completeness, Gap]
 
 ## Requirement Clarity
@@ -19,6 +19,6 @@
 - [ ] CHK010 Is "automatic retry logic" defined with specific backoff parameters? [Clarity, Spec §FR-018]
 
 ## Edge Case Coverage
-- [ ] CHK011 Are requirements defined for scenarios where the LLM provider is completely unreachable? [Edge Case, Gap]
+- [x] CHK011 Are requirements defined for scenarios where the LLM provider is completely unreachable? [Edge Case, Gap]
-- [ ] CHK012 Are requirements defined for handling "token limit exceeded" errors with large logs? [Edge Case, Gap]
+- [x] CHK012 Are requirements defined for handling "token limit exceeded" errors with large logs? [Edge Case, Gap]
-- [ ] CHK013 Are requirements defined for invalid/expired API keys during task execution? [Edge Case, Gap]
+- [x] CHK013 Are requirements defined for invalid/expired API keys during task execution? [Edge Case, Gap]

specs/017-llm-analysis-plugin/checklists/ux-usability.md

@@ -7,9 +7,9 @@
 ## Requirement Completeness
 - [ ] CHK001 Are requirements defined for the "Validate" button state during active execution (loading/disabled)? [Completeness, Gap]
 - [ ] CHK002 Are feedback requirements defined for successful/failed connection tests in Settings? [Completeness, Gap]
-- [ ] CHK003 Are requirements specified for viewing historical validation reports? [Completeness, Spec §US1]
+- [x] CHK003 Are requirements specified for viewing historical validation reports? [Completeness, Spec §US1]
-- [ ] CHK004 Are requirements defined for the notification content layout (summary vs. link)? [Completeness, Spec §FR-015]
+- [x] CHK004 Are requirements defined for the notification content layout (summary vs. link)? [Completeness, Spec §FR-015]
-- [ ] CHK005 Are requirements defined for the "Generate Commit" interaction flow (modal vs. inline)? [Completeness, Spec §US4]
+- [x] CHK005 Are requirements defined for the "Generate Commit" interaction flow (modal vs. inline)? [Completeness, Spec §US4]
 
 ## Requirement Clarity
 - [ ] CHK006 Is "visual representation" defined with resolution or format constraints? [Clarity, Spec §FR-005]
@@ -20,5 +20,5 @@
 - [ ] CHK009 Are error messages consistent with the application's existing error handling standards? [Consistency, Gap]
 
 ## Edge Case Coverage
-- [ ] CHK010 Are requirements defined for when a dashboard cannot be rendered (e.g., 404)? [Edge Case, Gap]
+- [x] CHK010 Are requirements defined for when a dashboard cannot be rendered (e.g., 404)? [Edge Case, Gap]
 - [ ] CHK011 Are requirements defined for when the generated commit message is empty or invalid? [Edge Case, Gap]

specs/017-llm-analysis-plugin/contracts/modules.md

@@ -0,0 +1,107 @@
+# Module Contracts: LLM Analysis Plugin
+
+**Feature**: `017-llm-analysis-plugin`
+**Protocol**: `semantic_protocol.md`
+
+## Backend Modules
+
+### Plugin Entry Point
+
+```python
+# [DEF:backend/src/plugins/llm_analysis/plugin.py:Module]
+# @TIER: STANDARD
+# @SEMANTICS: plugin, task_handler, validation, documentation
+# @PURPOSE: Orchestrate LLM-based analysis tasks (Dashboard Validation, Documentation) within the Plugin architecture.
+# @LAYER: Domain
+# @RELATION: DEPENDS_ON -> backend/src/plugins/llm_analysis/service.py
+# @RELATION: IMPLEMENTS -> backend/src/core/plugin_base.py
+# @INVARIANT: All tasks must report status updates via WebSocket.
+
+# [DEF:validate_dashboard:Function]
+# @PURPOSE: Analyze dashboard health using screenshot and logs.
+# @PRE: Dashboard ID exists and provider is configured.
+# @POST: ValidationResult is persisted and notification sent if failed.
+# [/DEF:validate_dashboard]
+
+# [DEF:generate_documentation:Function]
+# @PURPOSE: Generate and apply metadata descriptions for datasets.
+# @PRE: Dataset is accessible and schema is valid.
+# @POST: Dataset metadata is updated in the database.
+# [/DEF:generate_documentation]
+
+# [/DEF:backend/src/plugins/llm_analysis/plugin.py]
+```
+
+### LLM Service
+
+```python
+# [DEF:backend/src/plugins/llm_analysis/service.py:Module]
+# @TIER: CRITICAL
+# @SEMANTICS: llm, api, client, retry, prompt
+# @PURPOSE: Execute reliable interactions with external LLM providers (OpenAI, etc.) with retry logic and prompt management.
+# @LAYER: Infrastructure
+# @RELATION: CALLS -> external_api
+# @RELATION: DEPENDS_ON -> backend/src/services/llm_provider.py
+# @INVARIANT: API Keys must never be logged in plain text.
+
+# [DEF:analyze_multimodal:Function]
+# @PURPOSE: Send image and text context to LLM for analysis.
+# @PRE: Provider is active and quota is available.
+# @POST: Returns structured analysis or raises RetryError.
+# @SIDE_EFFECT: Makes external HTTP request.
+# [/DEF:analyze_multimodal]
+
+# [/DEF:backend/src/plugins/llm_analysis/service.py]
+```
+
+### Provider Management Service
+
+```python
+# [DEF:backend/src/services/llm_provider.py:Module]
+# @TIER: CRITICAL
+# @SEMANTICS: security, config, encryption, provider
+# @PURPOSE: Manage lifecycle and secure storage of LLM Provider configurations.
+# @LAYER: Domain
+# @RELATION: DEPENDS_ON -> backend/src/core/database.py
+# @INVARIANT: Stored API keys must be encrypted at rest.
+
+# [DEF:get_provider_client:Function]
+# @PURPOSE: Instantiate an authenticated LLM client for a specific provider.
+# @PRE: Provider ID exists and is active.
+# @POST: Returns configured client instance with decrypted key.
+# [/DEF:get_provider_client]
+
+# [/DEF:backend/src/services/llm_provider.py]
+```
+
+### Data Models
+
+```python
+# [DEF:backend/src/plugins/llm_analysis/models.py:Module]
+# @TIER: TRIVIAL
+# @SEMANTICS: dto, pydantic, schema
+# @PURPOSE: Define Pydantic models for configuration, requests, and results.
+# @LAYER: Domain/Data
+# [/DEF:backend/src/plugins/llm_analysis/models.py]
+```
+
+## Frontend Components
+
+### Configuration UI
+
+```html
+<!-- [DEF:frontend/src/components/llm/ProviderConfig.svelte:Component] -->
+<!-- @TIER: STANDARD -->
+<!-- @PURPOSE: Form for adding/editing LLM providers with connection testing. -->
+<!-- @RELATION: CALLS -> /api/settings/llm/providers -->
+<!-- [/DEF:frontend/src/components/llm/ProviderConfig.svelte] -->
+```
+
+### Validation Report
+
+```html
+<!-- [DEF:frontend/src/components/llm/ValidationReport.svelte:Component] -->
+<!-- @TIER: STANDARD -->
+<!-- @PURPOSE: Display formatted analysis results including screenshot and issues list. -->
+<!-- @INVARIANT: Must handle missing screenshots gracefully. -->
+<!-- [/DEF:frontend/src/components/llm/ValidationReport.svelte] -->

specs/017-llm-analysis-plugin/tasks.md

@@ -29,9 +29,9 @@
 
 **Goal**: Implement core services and shared infrastructure.
 
-- [ ] T008 Implement `LLMProviderService` in `backend/src/services/llm_provider.py` (CRUD for providers, encryption)
+- [ ] T008 Implement `LLMProviderService` in `backend/src/services/llm_provider.py` (CRUD for providers, AES-256 encryption)
-- [ ] T009 Implement `ScreenshotService` in `backend/src/plugins/llm_analysis/service.py` (Playwright + API strategies)
+- [ ] T009 Implement `ScreenshotService` in `backend/src/plugins/llm_analysis/service.py` (Playwright + API strategies, fallback logic)
-- [ ] T010 Implement `LLMClient` in `backend/src/plugins/llm_analysis/service.py` (OpenAI SDK wrapper, retry logic with tenacity)
+- [ ] T010 Implement `LLMClient` in `backend/src/plugins/llm_analysis/service.py` (OpenAI SDK wrapper, retry logic with tenacity, rate limit handling)
 - [ ] T011 Create `backend/src/plugins/llm_analysis/plugin.py` with `PluginBase` implementation stubs
 - [ ] T012 Define database schema updates for `LLMProviderConfig` in `backend/src/models/llm.py` (or appropriate location)
 - [ ] T013 Run migration to create new tables (if using SQLAlchemy/Alembic) or update SQLite schema
@@ -42,10 +42,10 @@
 
 - [ ] T014 [US1] Implement `validate_dashboard` task logic in `backend/src/plugins/llm_analysis/plugin.py`
 - [ ] T015 [US1] Implement log retrieval logic (fetch recent logs) in `backend/src/plugins/llm_analysis/plugin.py`
-- [ ] T016 [US1] Construct multimodal prompt (image + text) in `backend/src/plugins/llm_analysis/service.py`
+- [ ] T016 [US1] Construct multimodal prompt (image + text) in `backend/src/plugins/llm_analysis/service.py` (ensure data privacy/masking)
 - [ ] T017 [US1] Implement result parsing and persistence (ValidationResult) in `backend/src/plugins/llm_analysis/plugin.py`
 - [ ] T018 [US1] Add `validate` endpoint trigger in `backend/src/api/routes/tasks.py` (or reuse existing dispatch)
-- [ ] T019 [US1] Implement notification dispatch (Email/Pulse) on failure in `backend/src/plugins/llm_analysis/plugin.py`
+- [ ] T019 [US1] Implement notification dispatch (Email/Pulse) on failure in `backend/src/plugins/llm_analysis/plugin.py` (Summary + Link format)
 - [ ] T020 [US1] Create `frontend/src/components/llm/ValidationReport.svelte` for viewing results
 - [ ] T021 [US1] Add "Validate" button to `frontend/src/components/DashboardGrid.svelte` (or Environments list)
 - [ ] T022 [US1] Enable scheduling for validation tasks in `backend/src/core/scheduler.py` (if not automatic via TaskManager)
@@ -56,8 +56,8 @@
 
 - [ ] T023 [US2] Implement `generate_documentation` task logic in `backend/src/plugins/llm_analysis/plugin.py`
 - [ ] T024 [US2] Implement metadata fetching (schema, columns) in `backend/src/plugins/llm_analysis/plugin.py`
-- [ ] T025 [US2] Construct documentation prompt in `backend/src/plugins/llm_analysis/service.py`
+- [ ] T025 [US2] Construct documentation prompt in `backend/src/plugins/llm_analysis/service.py` (handle schema changes)
-- [ ] T026 [US2] Implement metadata update logic (write back to DB) in `backend/src/services/mapping_service.py` (or relevant service)
+- [ ] T026 [US2] Implement metadata update logic (write back to DB) in `backend/src/services/mapping_service.py` (handle partial failures)
 - [ ] T027 [US2] Add "Generate Docs" button to `frontend/src/components/tools/MapperTool.svelte` (or Dataset view)
 - [ ] T028 [US2] Create feedback/preview UI component `frontend/src/components/llm/DocPreview.svelte` (optional but recommended)
 
@@ -87,9 +87,10 @@
 
 - [ ] T039 Verify all permissions (`plugin:llm:validate`, etc.) are registered and enforceable
 - [ ] T040 Verify i18n strings for all new UI components
-- [ ] T041 Run full end-to-end test of Dashboard Validation flow
+- [ ] T041 Run full end-to-end test of Dashboard Validation flow (including fallback scenarios)
 - [ ] T042 Run full end-to-end test of Documentation flow
 - [ ] T043 Update `README.md` with new plugin capabilities
+- [ ] T044 Verify API key masking in all UI responses and logs
 
 ## Implementation Strategy