From a116ba77d86742f23865ff1b416fc60c5cb68247 Mon Sep 17 00:00:00 2001 From: busya Date: Sat, 28 Feb 2026 00:04:55 +0300 Subject: [PATCH] workflows update --- .agent/workflows/audit-test.md | 68 +++++++++++-- .agent/workflows/read_semantic.md | 2 +- .agent/workflows/speckit.analyze.md | 1 + .agent/workflows/speckit.implement.md | 17 +++- .agent/workflows/speckit.plan.md | 34 +++++-- .agent/workflows/speckit.tasks.md | 17 +++- .agent/workflows/speckit.test.md | 1 + .codex/prompts/audit-test.md | 68 +++++++++++-- .codex/prompts/read_semantic.md | 2 +- .codex/prompts/speckit.analyze.md | 1 + .codex/prompts/speckit.implement.md | 17 +++- .codex/prompts/speckit.plan.md | 34 +++++-- .codex/prompts/speckit.tasks.md | 17 +++- .codex/prompts/speckit.test.md | 13 +-- .kilocode/workflows/audit-test.md | 103 ++++++++++++++++++++ .kilocode/workflows/speckit.implement.md | 6 +- .kilocode/workflows/speckit.plan.md | 8 +- .kilocode/workflows/speckit.tasks.md | 4 +- .kilocode/workflows/speckit.test.md | 11 ++- backend/src/api/routes/dashboards.py | 5 +- backend/src/services/resource_service.py | 65 +++++++++++- frontend/src/routes/dashboards/+page.svelte | 10 ++ generate_semantic_map.py | 56 +++++++---- run.sh | 65 ++++++++++++ 24 files changed, 534 insertions(+), 91 deletions(-) create mode 100644 .kilocode/workflows/audit-test.md diff --git a/.agent/workflows/audit-test.md b/.agent/workflows/audit-test.md index d13f3fe7..775db586 100644 --- a/.agent/workflows/audit-test.md +++ b/.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_`). +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_CONTRACT`, @TEST_FIXTURE, @TEST_EDGE, @TEST_INVARIANT 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 -> ` 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_`? -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." } \ No newline at end of file diff --git a/.agent/workflows/read_semantic.md b/.agent/workflows/read_semantic.md index dcb78c2a..819ffdf7 100644 --- a/.agent/workflows/read_semantic.md +++ b/.agent/workflows/read_semantic.md @@ -1,4 +1,4 @@ --- description: USE SEMANTIC --- -Прочитай .specify/memory/semantics.md (или .ai/standards/semantics.md, если не найден). ОБЯЗАТЕЛЬНО используй его при разработке +Прочитай .ai/standards/semantics.md. ОБЯЗАТЕЛЬНО используй его при разработке diff --git a/.agent/workflows/speckit.analyze.md b/.agent/workflows/speckit.analyze.md index 7b495d79..ff67d98c 100644 --- a/.agent/workflows/speckit.analyze.md +++ b/.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 diff --git a/.agent/workflows/speckit.implement.md b/.agent/workflows/speckit.implement.md index 41da7b93..28118b1c 100644 --- a/.agent/workflows/speckit.implement.md +++ b/.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 diff --git a/.agent/workflows/speckit.plan.md b/.agent/workflows/speckit.plan.md index da802a82..6c515bf8 100644 --- a/.agent/workflows/speckit.plan.md +++ b/.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` diff --git a/.agent/workflows/speckit.tasks.md b/.agent/workflows/speckit.tasks.md index e09112bb..b1852909 100644 --- a/.agent/workflows/speckit.tasks.md +++ b/.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 diff --git a/.agent/workflows/speckit.test.md b/.agent/workflows/speckit.test.md index fcaf0b77..98eb847e 100644 --- a/.agent/workflows/speckit.test.md +++ b/.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] ``` --- diff --git a/.codex/prompts/audit-test.md b/.codex/prompts/audit-test.md index 737a3d51..775db586 100644 --- a/.codex/prompts/audit-test.md +++ b/.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_`). +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_` 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 -> ` 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_`? -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." } \ No newline at end of file diff --git a/.codex/prompts/read_semantic.md b/.codex/prompts/read_semantic.md index dcb78c2a..819ffdf7 100644 --- a/.codex/prompts/read_semantic.md +++ b/.codex/prompts/read_semantic.md @@ -1,4 +1,4 @@ --- description: USE SEMANTIC --- -Прочитай .specify/memory/semantics.md (или .ai/standards/semantics.md, если не найден). ОБЯЗАТЕЛЬНО используй его при разработке +Прочитай .ai/standards/semantics.md. ОБЯЗАТЕЛЬНО используй его при разработке diff --git a/.codex/prompts/speckit.analyze.md b/.codex/prompts/speckit.analyze.md index 7b495d79..ff67d98c 100644 --- a/.codex/prompts/speckit.analyze.md +++ b/.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 diff --git a/.codex/prompts/speckit.implement.md b/.codex/prompts/speckit.implement.md index 41da7b93..28118b1c 100644 --- a/.codex/prompts/speckit.implement.md +++ b/.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 diff --git a/.codex/prompts/speckit.plan.md b/.codex/prompts/speckit.plan.md index da802a82..6c515bf8 100644 --- a/.codex/prompts/speckit.plan.md +++ b/.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` diff --git a/.codex/prompts/speckit.tasks.md b/.codex/prompts/speckit.tasks.md index e09112bb..b1852909 100644 --- a/.codex/prompts/speckit.tasks.md +++ b/.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 diff --git a/.codex/prompts/speckit.test.md b/.codex/prompts/speckit.test.md index 32b6d77a..2c8b2e37 100644 --- a/.codex/prompts/speckit.test.md +++ b/.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_ from semantics header +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,7 +40,7 @@ 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_ fixtures @@ -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_ from semantic header +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 diff --git a/.kilocode/workflows/audit-test.md b/.kilocode/workflows/audit-test.md new file mode 100644 index 00000000..775db586 --- /dev/null +++ b/.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 -> ` 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." +} \ No newline at end of file diff --git a/.kilocode/workflows/speckit.implement.md b/.kilocode/workflows/speckit.implement.md index 84876f6c..60afc3dc 100644 --- a/.kilocode/workflows/speckit.implement.md +++ b/.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 diff --git a/.kilocode/workflows/speckit.plan.md b/.kilocode/workflows/speckit.plan.md index 3c3be2f4..328d83b3 100644 --- a/.kilocode/workflows/speckit.plan.md +++ b/.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**: diff --git a/.kilocode/workflows/speckit.tasks.md b/.kilocode/workflows/speckit.tasks.md index fa98caa3..14a2ac28 100644 --- a/.kilocode/workflows/speckit.tasks.md +++ b/.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 diff --git a/.kilocode/workflows/speckit.test.md b/.kilocode/workflows/speckit.test.md index 2e319b89..ca650f6d 100644 --- a/.kilocode/workflows/speckit.test.md +++ b/.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 @@ -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_ from semantics header +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 diff --git a/backend/src/api/routes/dashboards.py b/backend/src/api/routes/dashboards.py index 10b42dc8..efa82552 100644 --- a/backend/src/api/routes/dashboards.py +++ b/backend/src/api/routes/dashboards.py @@ -57,7 +57,10 @@ 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$", + ) # [/DEF:LastTask:DataClass] # [DEF:DashboardItem:DataClass] diff --git a/backend/src/services/resource_service.py b/backend/src/services/resource_service.py index 9b1a4379..d053305c 100644 --- a/backend/src/services/resource_service.py +++ b/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,7 +40,7 @@ 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, @@ -60,10 +61,11 @@ class ResourceService: git_status = self._get_git_status_for_dashboard(dashboard_id) dashboard_dict['git_status'] = git_status - # 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 +74,59 @@ class ResourceService: logger.info(f"[ResourceService][Coherence:OK] Fetched {len(result)} dashboards with status") return result # [/DEF:get_dashboards_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) + return { + "task_id": str(getattr(last_task, "id", "")), + "status": str(getattr(last_task, "status", "")), + } + # [/DEF:_get_last_llm_task_for_dashboard:Function] # [DEF:get_datasets_with_status:Function] # @PURPOSE: Fetch datasets from environment with mapping progress and last task status diff --git a/frontend/src/routes/dashboards/+page.svelte b/frontend/src/routes/dashboards/+page.svelte index f0d80abd..5f2c0d02 100644 --- a/frontend/src/routes/dashboards/+page.svelte +++ b/frontend/src/routes/dashboards/+page.svelte @@ -664,10 +664,14 @@ switch (status.toLowerCase()) { case "running": return ''; + case "pending": + return ''; case "success": return ''; + case "failed": case "error": return ''; + case "awaiting_input": case "waiting_input": return ''; default: @@ -928,10 +932,16 @@ {#if dashboard.lastTask.status.toLowerCase() === "running"} {$t.dashboard?.task_running} + {:else if dashboard.lastTask.status.toLowerCase() === "pending"} + {$t.dashboard?.task_running} {:else if dashboard.lastTask.status.toLowerCase() === "success"} {$t.dashboard?.task_done} + {:else if dashboard.lastTask.status.toLowerCase() === "failed"} + {$t.dashboard?.task_failed} {:else if dashboard.lastTask.status.toLowerCase() === "error"} {$t.dashboard?.task_failed} + {:else if dashboard.lastTask.status.toLowerCase() === "awaiting_input"} + {$t.dashboard?.task_waiting} {:else if dashboard.lastTask.status.toLowerCase() === "waiting_input"} {$t.dashboard?.task_waiting} {/if} diff --git a/generate_semantic_map.py b/generate_semantic_map.py index fe876658..738c01e0 100644 --- a/generate_semantic_map.py +++ b/generate_semantic_map.py @@ -94,28 +94,35 @@ OUTPUT_COMPRESSED_MD = ".ai/PROJECT_MAP.md" OUTPUT_MODULE_MAP_MD = ".ai/MODULE_MAP.md" REPORTS_DIR = "semantics/reports" -# Tier-based mandatory tags +# Tier-based mandatory tags aligned with .ai/standards/semantics.md TIER_MANDATORY_TAGS = { Tier.CRITICAL: { "Module": ["PURPOSE", "LAYER", "SEMANTICS", "TIER", "INVARIANT"], - "Component": ["PURPOSE", "LAYER", "SEMANTICS", "TIER", "INVARIANT"], - "Function": ["PURPOSE", "PRE", "POST"], - "Class": ["PURPOSE", "TIER"] + "Component": ["PURPOSE", "LAYER", "SEMANTICS", "TIER", "INVARIANT", "UX_STATE", "UX_FEEDBACK", "UX_RECOVERY", "UX_REATIVITY"], + "Function": ["PURPOSE", "PRE", "POST", "TEST_CONTRACT", "TEST_FIXTURE", "TEST_EDGE", "TEST_INVARIANT"], + "Class": ["PURPOSE", "TIER", "INVARIANT"], + "Store": ["PURPOSE", "TIER", "INVARIANT"] }, Tier.STANDARD: { "Module": ["PURPOSE", "LAYER", "SEMANTICS", "TIER"], - "Component": ["PURPOSE", "LAYER", "SEMANTICS", "TIER"], + "Component": ["PURPOSE", "LAYER", "SEMANTICS", "TIER", "UX_STATE"], "Function": ["PURPOSE", "PRE", "POST"], - "Class": ["PURPOSE", "TIER"] + "Class": ["PURPOSE", "TIER"], + "Store": ["PURPOSE", "TIER"] }, Tier.TRIVIAL: { - "Module": ["PURPOSE", "TIER"], - "Component": ["PURPOSE", "TIER"], + "Module": ["PURPOSE"], + "Component": ["PURPOSE"], "Function": ["PURPOSE"], - "Class": ["PURPOSE", "TIER"] + "Class": ["PURPOSE"], + "Store": ["PURPOSE"] } } +ALLOWED_RELATION_PREDICATES = { + "DEPENDS_ON", "CALLS", "INHERITS", "IMPLEMENTS", "DISPATCHES", "BINDS_TO" +} + # Tier-based belief state requirements TIER_BELIEF_REQUIRED = { Tier.CRITICAL: True, @@ -252,7 +259,17 @@ class SemanticEntity: self.start_line )) - # 3. Check for Belief State Logging based on TIER + # 3. Validate relation predicates against GRACE-Poly allowlist + for rel in self.relations: + rel_type = rel.get("type", "").upper() + if rel_type and rel_type not in ALLOWED_RELATION_PREDICATES: + self.compliance_issues.append(ComplianceIssue( + f"Invalid @RELATION predicate: {rel_type}. Allowed: {', '.join(sorted(ALLOWED_RELATION_PREDICATES))}", + Severity.ERROR if tier == Tier.CRITICAL else Severity.WARNING, + self.start_line + )) + + # 4. Check for Belief State Logging based on TIER if self.type == "Function": belief_required = TIER_BELIEF_REQUIRED.get(tier, False) if belief_required: @@ -270,7 +287,7 @@ class SemanticEntity: self.start_line )) - # 4. Check for @INVARIANT in CRITICAL tier + # 5. Check for @INVARIANT in CRITICAL tier if tier == Tier.CRITICAL and self.type in ["Module", "Component", "Class"]: if "INVARIANT" not in [k.upper() for k in self.tags.keys()]: self.compliance_issues.append(ComplianceIssue( @@ -338,7 +355,7 @@ def get_patterns(lang: str) -> Dict[str, Pattern]: if lang == "python": return { "anchor_start": re.compile(r"#\s*\[DEF:(?P[\w\.]+):(?P\w+)\]"), - "anchor_end": re.compile(r"#\s*\[/DEF:(?P[\w\.]+)(?::\w+)?\]"), + "anchor_end": re.compile(r"#\s*\[/DEF:(?P[\w\.]+):(?P\w+)\]"), "tag": re.compile(r"#\s*@(?P[A-Z_]+):\s*(?P.*)"), "relation": re.compile(r"#\s*@RELATION:\s*(?P\w+)\s*->\s*(?P.*)"), "func_def": re.compile(r"^\s*(async\s+)?def\s+(?P\w+)"), @@ -348,11 +365,11 @@ def get_patterns(lang: str) -> Dict[str, Pattern]: else: return { "html_anchor_start": re.compile(r""), - "html_anchor_end": re.compile(r""), + "html_anchor_end": re.compile(r""), "js_anchor_start": re.compile(r"//\s*\[DEF:(?P[\w\.]+):(?P\w+)\]"), - "js_anchor_end": re.compile(r"//\s*\[/DEF:(?P[\w\.]+)(?::\w+)?\]"), + "js_anchor_end": re.compile(r"//\s*\[/DEF:(?P[\w\.]+):(?P\w+)\]"), "html_tag": re.compile(r"@(?P[A-Z_]+):\s*(?P.*)"), - "jsdoc_tag": re.compile(r"\*\s*@(?P[a-zA-Z]+)\s+(?P.*)"), + "jsdoc_tag": re.compile(r"\*\s*@(?P[A-Za-z_]+)\s*:?\s*(?P.*)"), "relation": re.compile(r"//\s*@RELATION:\s*(?P\w+)\s*->\s*(?P.*)"), "func_def": re.compile(r"^\s*(export\s+)?(async\s+)?function\s+(?P\w+)"), "console_log": re.compile(r"console\.log\s*\(\s*['\"`]\[[\w_]+\]\[[A-Za-z0-9_:]+\]"), @@ -550,22 +567,23 @@ def parse_file(full_path: str, rel_path: str, lang: str) -> Tuple[List[SemanticE if match_end: name = match_end.group("name") + type_ = match_end.group("type") if not stack: issues.append(ComplianceIssue( - f"{rel_path}:{lineno} Found closing anchor [/DEF:{name}] without opening anchor.", + f"{rel_path}:{lineno} Found closing anchor [/DEF:{name}:{type_}] without opening anchor.", Severity.ERROR, lineno )) continue top = stack[-1] - if top.name == name: + if top.name == name and top.type == type_: top.end_line = lineno stack.pop() else: issues.append(ComplianceIssue( - f"{rel_path}:{lineno} Mismatched closing anchor. Expected [/DEF:{top.name}], found [/DEF:{name}].", + f"{rel_path}:{lineno} Mismatched closing anchor. Expected [/DEF:{top.name}:{top.type}], found [/DEF:{name}:{type_}].", Severity.ERROR, lineno )) @@ -1039,7 +1057,7 @@ class SemanticMapGenerator: # Write Relations for rel in entity.relations: - if rel['type'] in ['DEPENDS_ON', 'CALLS', 'INHERITS', 'IMPLEMENTS', 'DISPATCHES']: + if rel['type'] in ['DEPENDS_ON', 'CALLS', 'INHERITS', 'IMPLEMENTS', 'DISPATCHES', 'BINDS_TO']: f.write(f"{indent} - 🔗 {rel['type']} -> `{rel['target']}`\n") if level < 3: diff --git a/run.sh b/run.sh index cff8f14e..02eb7201 100755 --- a/run.sh +++ b/run.sh @@ -61,6 +61,71 @@ validate_env() { validate_env +# Database connectivity preflight +check_database() { + # Keep resolution order aligned with backend/src/core/database.py defaults. + local DB_URL="${DATABASE_URL:-${POSTGRES_URL:-postgresql+psycopg2://postgres:postgres@localhost:5432/ss_tools}}" + + # SQLite does not require external service. + if [[ "$DB_URL" == sqlite* ]]; then + echo "Database preflight: sqlite detected, skipping PostgreSQL connectivity check." + return + fi + + local DB_HOST DB_PORT + read -r DB_HOST DB_PORT < <( + python3 - "$DB_URL" <<'PY' +import sys +from urllib.parse import urlparse + +url = sys.argv[1] +if "://" not in url: + print("localhost 5432") + raise SystemExit(0) + +# Support SQLAlchemy schemes like postgresql+psycopg2://... +scheme, rest = url.split("://", 1) +parsed = urlparse(f"{scheme.split('+', 1)[0]}://{rest}") +host = parsed.hostname or "localhost" +port = parsed.port or 5432 +print(f"{host} {port}") +PY + ) + + local check_cmd + check_cmd='import socket,sys; socket.create_connection((sys.argv[1], int(sys.argv[2])), timeout=1).close()' + + if python3 -c "$check_cmd" "$DB_HOST" "$DB_PORT" >/dev/null 2>&1; then + echo "Database preflight: reachable at ${DB_HOST}:${DB_PORT}." + return + fi + + echo "Database preflight: cannot connect to ${DB_HOST}:${DB_PORT}." + + # For local development defaults, attempt to auto-start bundled PostgreSQL. + if [ "$DB_HOST" = "localhost" ] && [ "$DB_PORT" = "5432" ] && command -v docker >/dev/null 2>&1; then + if [ -f "docker-compose.yml" ]; then + echo "Attempting to start local PostgreSQL via docker compose (service: db)..." + docker compose up -d db || true + fi + fi + + for _ in {1..20}; do + if python3 -c "$check_cmd" "$DB_HOST" "$DB_PORT" >/dev/null 2>&1; then + echo "Database preflight: reachable at ${DB_HOST}:${DB_PORT}." + return + fi + sleep 1 + done + + echo "Error: PostgreSQL is unavailable at ${DB_HOST}:${DB_PORT}." + echo "Run: docker compose up -d db" + echo "Or set DATABASE_URL/POSTGRES_URL to a reachable database." + exit 1 +} + +check_database + # Backend dependency management setup_backend() { if [ "$SKIP_INSTALL" = true ]; then