workflows update

.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 -> <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_`?
-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.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_ 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