From 2ed66bfebc1fbe11c3638c4f158a3bd3aee675d1 Mon Sep 17 00:00:00 2001 From: busya Date: Fri, 27 Mar 2026 21:27:31 +0300 Subject: [PATCH] semantics --- .ai/PERSONA.md | 4 +- .ai/PROJECT_MAP.md | 44 + .ai/ROOT.md | 23 +- .ai/standards/api_design.md | 2 +- .ai/standards/architecture.md | 2 +- .ai/standards/constitution.md | 7 +- .ai/standards/plugin_design.md | 2 +- .ai/standards/semantics.md | 76 +- .ai/standards/ui_design.md | 6 +- .ai/structure/MODULE_MAP.md | 5726 +++++ .ai/structure/PROJECT_MAP.md | 901 +- .kilo/mcp.json | 52 + .kilocode/workflows/speckit.semantics.md | 10 +- backend/src/api/routes/__init__.py | 37 +- .../routes/__tests__/test_assistant_api.py | 2 - backend/src/api/routes/clean_release_v2.py | 12 +- backend/src/api/routes/llm.py | 32 +- backend/src/api/routes/plugins.py | 15 +- backend/src/api/routes/reports.py | 2 + backend/src/api/routes/tasks.py | 150 +- backend/src/app.py | 133 +- backend/src/core/config_models.py | 36 +- backend/src/core/superset_client.py | 282 +- backend/src/core/task_manager/__init__.py | 4 +- backend/src/core/task_manager/context.py | 4 +- backend/src/core/task_manager/manager.py | 109 +- backend/src/core/task_manager/models.py | 16 +- backend/src/core/task_manager/persistence.py | 232 +- backend/src/core/task_manager/task_logger.py | 8 +- .../models/__tests__/test_clean_release.py | 157 +- backend/src/models/__tests__/test_models.py | 6 +- backend/src/schemas/__init__.py | 4 +- backend/src/schemas/auth.py | 42 +- backend/src/schemas/health.py | 10 +- backend/src/schemas/profile.py | 30 +- backend/src/schemas/settings.py | 44 +- backend/src/scripts/__init__.py | 4 +- backend/src/scripts/clean_release_cli.py | 88 +- backend/src/scripts/clean_release_tui.py | 182 +- backend/src/scripts/create_admin.py | 19 +- .../scripts/dataset_dashboard_analysis.json | 8 +- .../src/scripts/migrate_sqlite_to_postgres.py | 65 +- .../src/scripts/seed_superset_load_test.py | 157 +- backend/src/services/auth_service.py | 22 +- .../src/services/clean_release/__init__.py | 10 +- .../__tests__/test_audit_service.py | 2 +- .../__tests__/test_compliance_orchestrator.py | 76 +- .../__tests__/test_manifest_builder.py | 20 +- .../__tests__/test_policy_engine.py | 85 +- .../__tests__/test_preparation_service.py | 2 +- .../__tests__/test_report_builder.py | 18 +- .../__tests__/test_source_isolation.py | 2 +- .../clean_release/__tests__/test_stages.py | 2 +- .../clean_release/approval_service.py | 67 +- .../clean_release/artifact_catalog_loader.py | 23 +- .../services/clean_release/audit_service.py | 28 +- .../compliance_execution_service.py | 94 +- .../clean_release/compliance_orchestrator.py | 68 +- .../clean_release/demo_data_service.py | 12 +- .../clean_release/manifest_builder.py | 42 +- .../clean_release/manifest_service.py | 21 +- .../services/clean_release/policy_engine.py | 76 +- .../policy_resolution_service.py | 36 +- .../clean_release/preparation_service.py | 31 +- .../clean_release/publication_service.py | 78 +- .../services/clean_release/report_builder.py | 19 +- .../src/services/clean_release/repository.py | 96 +- .../clean_release/source_isolation.py | 16 +- .../services/clean_release/stages/__init__.py | 27 +- .../src/services/clean_release/stages/base.py | 25 +- .../clean_release/stages/data_purity.py | 8 +- .../stages/internal_sources_only.py | 23 +- .../stages/manifest_consistency.py | 8 +- .../stages/no_external_endpoints.py | 23 +- backend/src/services/health_service.py | 118 +- backend/src/services/llm_provider.py | 82 +- backend/src/services/notifications/service.py | 156 +- .../src/services/reports/report_service.py | 90 +- .../core/migration/test_archive_parser.py | 7 +- .../migration/test_dry_run_orchestrator.py | 7 +- backend/tests/test_resource_hubs.py | 86 +- docs/architecture.md | 8 + frontend/src/components/Navbar.svelte | 13 +- frontend/src/components/Toast.svelte | 8 +- .../__tests__/task_log_viewer.test.js | 8 +- ...nager.unfinished_merge.integration.test.js | 4 +- .../provider_config.integration.test.js | 6 +- frontend/src/lib/Counter.svelte | 5 +- .../src/lib/api/__tests__/reports_api.test.js | 4 +- frontend/src/lib/api/reports.js | 4 +- .../lib/auth/__tests__/permissions.test.js | 4 +- frontend/src/lib/auth/permissions.js | 5 +- .../assistant_chat.integration.test.js | 6 +- ...ssistant_clarification.integration.test.js | 2 +- ...ssistant_first_message.integration.test.js | 6 +- .../__tests__/source_intake_panel.ux.test.js | 4 +- .../us2_semantic_workspace.ux.test.js | 4 +- .../__tests__/us3_execution_batch.ux.test.js | 54 +- .../validation_findings_panel.ux.test.js | 4 +- .../lib/components/health/HealthMatrix.svelte | 18 +- .../lib/components/health/PolicyForm.svelte | 23 +- .../lib/components/layout/Breadcrumbs.svelte | 8 +- .../src/lib/components/layout/Sidebar.svelte | 12 +- .../lib/components/layout/TaskDrawer.svelte | 17 +- .../lib/components/layout/TopNavbar.svelte | 14 +- .../__tests__/sidebarNavigation.test.js | 4 +- .../__tests__/test_breadcrumbs.svelte.js | 11 +- .../layout/__tests__/test_sidebar.svelte.js | 6 +- .../__tests__/test_taskDrawer.svelte.js | 6 +- .../layout/__tests__/test_topNavbar.svelte.js | 6 +- .../reports/__tests__/report_card.ux.test.js | 10 +- .../report_detail.integration.test.js | 6 +- .../__tests__/report_detail.ux.test.js | 4 +- .../__tests__/report_type_profiles.test.js | 4 +- .../reports_filter_performance.test.js | 4 +- .../reports/__tests__/reports_list.ux.test.js | 18 +- .../reports_page.integration.test.js | 6 +- .../components/reports/reportTypeProfiles.js | 4 +- .../stores/__tests__/assistantChat.test.js | 6 +- .../lib/stores/__tests__/mocks/env_public.js | 2 +- .../lib/stores/__tests__/mocks/environment.js | 7 +- .../lib/stores/__tests__/mocks/navigation.js | 6 +- .../src/lib/stores/__tests__/mocks/stores.js | 6 +- .../src/lib/stores/__tests__/setupTests.js | 6 +- .../src/lib/stores/__tests__/sidebar.test.js | 8 +- .../src/lib/stores/__tests__/test_activity.js | 6 +- .../__tests__/test_datasetReviewSession.js | 4 +- .../src/lib/stores/__tests__/test_sidebar.js | 4 +- .../lib/stores/__tests__/test_taskDrawer.js | 4 +- frontend/src/lib/ui/Button.svelte | 10 +- frontend/src/lib/ui/Card.svelte | 6 +- frontend/src/lib/ui/Icon.svelte | 13 + frontend/src/lib/ui/Input.svelte | 7 +- frontend/src/lib/ui/LanguageSwitcher.svelte | 6 +- frontend/src/lib/ui/PageHeader.svelte | 6 +- frontend/src/lib/ui/Select.svelte | 6 +- frontend/src/pages/Dashboard.svelte | 5 + frontend/src/pages/Settings.svelte | 25 +- frontend/src/routes/+error.svelte | 4 + frontend/src/routes/+layout.svelte | 3 +- frontend/src/routes/+page.svelte | 3 + frontend/src/routes/_contracts.md | 22 + frontend/src/routes/admin/users/+page.svelte | 7 + frontend/src/routes/dashboards/+page.svelte | 10 +- .../src/routes/dashboards/[id]/+page.svelte | 9 +- ...board-profile-override.integration.test.js | 4 +- .../__tests__/health_page.integration.test.js | 4 +- .../dataset_review_workspace.ux.test.js | 2 +- .../__tests__/dataset_review_entry.test.js | 2 +- .../__tests__/dataset_review_entry.ux.test.js | 2 +- frontend/src/routes/git/+page.svelte | 10 + .../profile-preferences.integration.test.js | 4 +- ...profile-settings-state.integration.test.js | 4 +- .../llm/[taskId]/report_page.contract.test.js | 2 +- .../__tests__/settings_page.ux.test.js | 10 +- .../routes/settings/connections/+page.svelte | 9 + frontend/src/routes/settings/git/+page.svelte | 10 +- .../__tests__/git_settings_page.ux.test.js | 7 +- frontend/src/routes/storage/+page.svelte | 6 +- .../src/routes/storage/backups/+page.svelte | 6 +- .../src/routes/tools/backups/+page.svelte | 9 +- frontend/src/routes/tools/debug/+page.svelte | 10 +- frontend/src/routes/tools/mapper/+page.svelte | 10 +- .../src/services/__tests__/gitService.test.js | 5 +- semantics/semantic_map.json | 20013 +++++++++------- .../contracts/modules.md | 108 +- specs/015-frontend-nav-redesign/plan.md | 2 +- specs/015-frontend-nav-redesign/tasks.md | 6 +- .../contracts/modules.md | 20 +- .../019-superset-ux-redesign/contracts/api.md | 6 +- .../contracts/modules.md | 26 +- .../contracts/modules.md | 12 +- .../contracts/modules.md | 18 +- .../checklists/release-readiness.md | 16 +- .../contracts/modules.md | 10 +- specs/023-clean-repo-enterprise/plan.md | 4 +- specs/023-clean-repo-enterprise/quickstart.md | 4 +- specs/023-clean-repo-enterprise/tasks.md | 6 +- .../023-clean-repo-enterprise/tests/README.md | 7 +- .../contracts/modules.md | 96 +- .../contracts/modules.md | 44 +- .../contracts/modules.md | 44 +- 182 files changed, 21186 insertions(+), 10254 deletions(-) create mode 100644 .ai/PROJECT_MAP.md create mode 100644 .ai/structure/MODULE_MAP.md create mode 100644 .kilo/mcp.json create mode 100644 frontend/src/routes/_contracts.md diff --git a/.ai/PERSONA.md b/.ai/PERSONA.md index 11e5f1e4..27cfcbeb 100644 --- a/.ai/PERSONA.md +++ b/.ai/PERSONA.md @@ -2,6 +2,8 @@ # @COMPLEXITY: 5 # @SEMANTICS: persona, tone_of_voice, interaction_rules, architect # @PURPOSE: Defines how the AI Agent MUST interact with the user and the codebase. +# @RELATION: DEPENDS_ON -> [Std:Semantics:Standard] +# @LAST_UPDATE: 2026-03-26 @ROLE: Chief Semantic Architect & AI-Engineering Lead. @PHILOSOPHY: "Смысл первичен. Код вторичен. ИИ — это семантический процессор, а не собеседник." @@ -39,4 +41,4 @@ **Я ожидаю от тебя уровня Senior Staff Engineer, который понимает устройство LLM, KV Cache и графов знаний.** -# [/DEF:Std:UserPersona:Standard] \ No newline at end of file +# [/DEF:Std:UserPersona:Standard] diff --git a/.ai/PROJECT_MAP.md b/.ai/PROJECT_MAP.md new file mode 100644 index 00000000..f54efe7d --- /dev/null +++ b/.ai/PROJECT_MAP.md @@ -0,0 +1,44 @@ +# [DEF:Project_Map:Root] +# @COMPLEXITY: 3 +# @PURPOSE: Canonical ownership record for repository structure navigation and generated project-map artifacts. +# @RELATION: DEPENDS_ON -> [Project_Knowledge_Map:Root] +# @RELATION: DEPENDS_ON -> [Std:Constitution:Standard] +# @RELATION: DEPENDS_ON -> [Std:UserPersona:Standard] +# @RELATION: BINDS_TO -> [MCP_Config:Block] +# @LAST_UPDATE: 2026-03-26 + +## Canonical ownership +- Canonical owner for `Project_Map` is this file: `.ai/PROJECT_MAP.md`. +- Generated structural snapshot lives at `.ai/structure/PROJECT_MAP.md` and is a backing artifact, not the canonical ownership document. +- References that previously pointed directly to `.ai/structure/PROJECT_MAP.md` for `Project_Map` should normalize to this file. + +## Canonical relations +- Root knowledge entry: `.ai/ROOT.md` -> `[DEF:Project_Knowledge_Map:Root]` +- Normalized project MCP configuration: `.kilo/mcp.json` -> `[DEF:MCP_Config:Block]` +- Repository constitution: `.ai/standards/constitution.md` -> `[DEF:Std:Constitution:Standard]` +- Repository persona: `.ai/PERSONA.md` -> `[DEF:Std:UserPersona:Standard]` + +## Generated snapshot handoff +- Use `.ai/structure/PROJECT_MAP.md` for the expanded generated module/file inventory. +- Regeneration may replace snapshot contents without changing canonical ownership of `Project_Map`. + +# [DEF:MCP_Config:Block] +# @COMPLEXITY: 3 +# @PURPOSE: Canonical ownership record for normalized project MCP configuration consumed by semantic workflows. +# @RELATION: DEPENDS_ON -> [Project_Map:Root] +# @RELATION: DEPENDS_ON -> [Std:Constitution:Standard] +# @RELATION: DEPENDS_ON -> [Std:UserPersona:Standard] +# @LAST_UPDATE: 2026-03-26 + +## Normalized config path +- Canonical project MCP config path is `.kilo/mcp.json`. +- For this repository, new docs and workflows must reference `.kilo/mcp.json` as the normalized MCP config. +- Do not introduce new canonical references to deprecated project MCP doc paths for ownership or workflow wiring. + +## Current semantic workflow binding +- AXIOM semantic workflows in `.kilocode/workflows/` bind to tools exposed through `.kilo/mcp.json`. +- The `axiom-core` server definition in `.kilo/mcp.json` is the normalized semantic-audit integration point for this repository. + +# [/DEF:MCP_Config:Block] + +# [/DEF:Project_Map:Root] diff --git a/.ai/ROOT.md b/.ai/ROOT.md index 1ee3ff1a..4a0a88b2 100644 --- a/.ai/ROOT.md +++ b/.ai/ROOT.md @@ -1,14 +1,19 @@ # [DEF:Project_Knowledge_Map:Root] # @COMPLEXITY: 5 -# @PURPOSE: Global navigation map for AI-Agent (GRACE Knowledge Graph). -# @LAST_UPDATE: 2026-02-20 +# @PURPOSE: Canonical GRACE navigation map for repository standards and semantic context. +# @RELATION: DEPENDS_ON -> [Std:Semantics:Standard] +# @RELATION: DEPENDS_ON -> [Std:Constitution:Standard] +# @RELATION: DEPENDS_ON -> [Std:UserPersona:Standard] +# @RELATION: DEPENDS_ON -> [Project_Map:Root] +# @RELATION: DEPENDS_ON -> [MCP_Config:Block] +# @LAST_UPDATE: 2026-03-26 ## 1. SYSTEM STANDARDS (Rules of the Game) Strict policies and formatting rules. * **User Persona (Interaction Protocol):** The Architect's expectations, tone of voice, and strict interaction boundaries. - * Ref: `.ai/standards/persona.md` -> `[DEF:Std:UserPersona]` + * Ref: `.ai/PERSONA.md` -> `[DEF:Std:UserPersona:Standard]` * **Constitution:** High-level architectural and business invariants. - * Ref: `.ai/standards/constitution.md` -> `[DEF:Std:Constitution]` + * Ref: `.ai/standards/constitution.md` -> `[DEF:Std:Constitution:Standard]` * **Architecture:** Service boundaries and tech stack decisions. * Ref: `.ai/standards/architecture.md` -> `[DEF:Std:Architecture]` * **Plugin Design:** Rules for building and integrating Plugins. @@ -18,7 +23,7 @@ Strict policies and formatting rules. * **UI Design:** SvelteKit and Tailwind CSS component standards. * Ref: `.ai/standards/ui_design.md` -> `[DEF:Std:UI_Svelte]` * **Semantic Mapping:** Using `[DEF:]` and belief scopes. - * Ref: `.ai/standards/semantics.md` -> `[DEF:Std:Semantics]` + * Ref: `.ai/standards/semantics.md` -> `[DEF:Std:Semantics:Standard]` ## 2. FEW-SHOT EXAMPLES (Patterns) Use these for code generation (Style Transfer). @@ -32,8 +37,10 @@ Use these for code generation (Style Transfer). * Ref: `.ai/shots/critical_module.py` -> `[DEF:Shot:Critical_Module]` ## 3. DOMAIN MAP (Modules) -* **High-level Module Map:** `.ai/structure/MODULE_MAP.md` -> `[DEF:Module_Map]` -* **Low-level Project Map:** `.ai/structure/PROJECT_MAP.md` -> `[DEF:Project_Map]` +* **High-level Module Map:** `.ai/MODULE_MAP.md` -> `[DEF:Module_Map]` +* **Canonical Project Map Ownership:** `.ai/PROJECT_MAP.md` -> `[DEF:Project_Map:Root]` +* **Generated Project Map Snapshot:** `.ai/structure/PROJECT_MAP.md` (backing generated artifact) +* **Normalized MCP Configuration:** `.kilo/mcp.json` -> `[DEF:MCP_Config:Block]` * **Apache Superset OpenAPI Source:** `.ai/openapi/superset_openapi.json` -> `[DEF:Doc:Superset_OpenAPI]` * **Apache Superset OpenAPI Split Index:** `.ai/openapi/superset/README.md` -> `[DEF:Doc:Superset_OpenAPI]` * **Superset OpenAPI Sections:** @@ -47,4 +54,4 @@ Use these for code generation (Style Transfer). * **Frontend Lib:** `frontend/src/lib` -> `[DEF:Module:Frontend_Lib]` * **Specifications:** `specs/` -> `[DEF:Module:Specs]` -# [/DEF:Project_Knowledge_Map] +# [/DEF:Project_Knowledge_Map:Root] diff --git a/.ai/standards/api_design.md b/.ai/standards/api_design.md index 38b3cb7b..65af288e 100644 --- a/.ai/standards/api_design.md +++ b/.ai/standards/api_design.md @@ -44,4 +44,4 @@ async def function_name(...): * Use `try-except` blocks within `belief_scope` to ensure proper error logging and classification. * Do not leak internal implementation details in error responses. -# [/DEF:Std:API_FastAPI] +# [/DEF:Std:API_FastAPI:Standard] diff --git a/.ai/standards/architecture.md b/.ai/standards/architecture.md index 6b3ba2b5..d71dcd37 100644 --- a/.ai/standards/architecture.md +++ b/.ai/standards/architecture.md @@ -20,4 +20,4 @@ * **Superset API:** Communication via REST API. * **Filesystem:** Local storage for backups and git repositories. -# [/DEF:Std:Architecture] +# [/DEF:Std:Architecture:Standard] diff --git a/.ai/standards/constitution.md b/.ai/standards/constitution.md index 201ac951..09788977 100644 --- a/.ai/standards/constitution.md +++ b/.ai/standards/constitution.md @@ -1,14 +1,15 @@ # [DEF:Std:Constitution:Standard] # @COMPLEXITY: 5 # @PURPOSE: Supreme Law of the Repository. High-level architectural and business invariants. +# @RELATION: DEPENDS_ON -> [Std:Semantics:Standard] # @VERSION: 2.3.0 -# @LAST_UPDATE: 2026-02-19 +# @LAST_UPDATE: 2026-03-26 # @INVARIANT: Any deviation from this Constitution constitutes a build failure. ## 1. CORE PRINCIPLES ### I. Semantic Protocol Compliance -* **Ref:** `[DEF:Std:Semantics]` (`ai/standards/semantic.md`) +* **Ref:** `[DEF:Std:Semantics:Standard]` (`.ai/standards/semantics.md`) * **Law:** All code must adhere to the Axioms (Meaning First, Contract First, etc.). * **Compliance:** Strict matching of Anchors (`[DEF]`), Tags (`@KEY`), and structures is mandatory. @@ -32,4 +33,4 @@ * **Non-Blocking:** API endpoints return Task ID immediately. * **Observability:** Real-time updates via WebSocket. -# [/DEF:Std:Constitution] +# [/DEF:Std:Constitution:Standard] diff --git a/.ai/standards/plugin_design.md b/.ai/standards/plugin_design.md index a31f205c..e4e50699 100644 --- a/.ai/standards/plugin_design.md +++ b/.ai/standards/plugin_design.md @@ -29,4 +29,4 @@ Plugins MUST use `TaskContext` for logging to ensure proper source attribution: 2. **Schema Validation:** Ensure the `get_schema()` precisely matches the `execute()` input expectations. 3. **Isolation:** Plugins should be self-contained and not depend on other plugins directly. Use core services (`ConfigManager`, `TaskManager`) via dependency injection or the provided `context`. -# [/DEF:Std:Plugin] +# [/DEF:Std:Plugin:Standard] diff --git a/.ai/standards/semantics.md b/.ai/standards/semantics.md index 04bf6235..bc4685f4 100644 --- a/.ai/standards/semantics.md +++ b/.ai/standards/semantics.md @@ -1,25 +1,65 @@ -# SYSTEM DIRECTIVE: GRACE-Poly (UX Edition) v2.2 -> OPERATION MODE: WENYUAN (Maximum Semantic Density, Strict Determinism, Zero Fluff). -> ROLE: AI Software Architect & Implementation Engine (Python/Svelte). +# [DEF:Std:Semantics:Standard] +# @COMPLEXITY: 5 +# @PURPOSE: Canonical GRACE protocol for semantic anchors, metadata, relations, and compliance levels. +# @RELATION: DEPENDS_ON -> [Project_Knowledge_Map:Root] +# @RELATION: DEPENDS_ON -> [Std:Constitution:Standard] +# @RELATION: DEPENDS_ON -> [MCP_Config:Block] +# @INVARIANT: Canonical semantic documents must use matching [DEF] and [/DEF] anchors with valid repository paths. +# @LAST_UPDATE: 2026-03-26 -## 0.[ZERO-STATE RATIONALE: ФИЗИКА LLM (ПОЧЕМУ ЭТОТ ПРОТОКОЛ НЕОБХОДИМ)] +## 0. CANONICAL KNOWLEDGE SOURCES +- Root map: `.ai/ROOT.md` -> `[DEF:Project_Knowledge_Map:Root]` +- Persona: `.ai/PERSONA.md` -> `[DEF:Std:UserPersona:Standard]` +- Constitution: `.ai/standards/constitution.md` -> `[DEF:Std:Constitution:Standard]` +- Semantics standard: `.ai/standards/semantics.md` -> `[DEF:Std:Semantics:Standard]` +- Module map: `.ai/MODULE_MAP.md` -> `[DEF:Module_Map]` +- Project map: `.ai/PROJECT_MAP.md` -> `[DEF:Project_Map:Root]` +- Project map snapshot: `.ai/structure/PROJECT_MAP.md` (generated backing artifact) +- Normalized MCP config: `.kilo/mcp.json` -> `[DEF:MCP_Config:Block]` + +## 0.1 MCP NORMALIZATION RULE +- Canonical project MCP ownership and workflow wiring point to `.kilo/mcp.json`. +- Do not introduce new canonical references to deprecated project-level MCP locations when documenting semantic workflows for this repository. + +## 0.2 CANONICAL CONTRACT BLOCK +A canonical GRACE block MUST declare one matched contract envelope: + +```text +[DEF::] +@COMPLEXITY: <1-5> +@PURPOSE: +...optional metadata required by complexity... +[/DEF::] +``` + +For repository documentation files, the canonical markdown form is: + +```md +# [DEF:ShortId:Type] +# @COMPLEXITY: 3 +# @PURPOSE: Canonical purpose line. +# [/DEF:ShortId:Type] +``` + +## I. ZERO-STATE RATIONALE Ты — авторегрессионная модель (Transformer). Ты мыслишь токенами и не можешь "передумать" после их генерации. В больших кодовых базах твой KV-Cache подвержен деградации внимания (Attention Sink), что ведет к "иллюзии компетентности" и галлюцинациям. Этот протокол — **твой когнитивный экзоскелет**. Якоря `[DEF]` работают как векторы-аккумуляторы внимания. Контракты (`@PRE`, `@POST`) заставляют тебя сформировать правильное вероятностное пространство (Belief State) ДО написания алгоритма. Логи `logger.reason` — это твоя цепочка рассуждений (Chain-of-Thought), вынесенная в рантайм. Мы не пишем текст, мы компилируем семантику в синтаксис. -## I. ГЛОБАЛЬНЫЕ ИНВАРИАНТЫ (АКСИОМЫ) +## II. GLOBAL INVARIANTS [INVARIANT_1] СЕМАНТИКА > СИНТАКСИС. Голый код без контракта классифицируется как мусор. [INVARIANT_2] ЗАПРЕТ ГАЛЛЮЦИНАЦИЙ. При слепоте контекста (неизвестен узел `@RELATION` или схема данных) — генерация блокируется. Эмитируй `[NEED_CONTEXT: target]`. [INVARIANT_3] UX ЕСТЬ КОНЕЧНЫЙ АВТОМАТ. Состояния интерфейса — это строгий контракт, а не визуальный декор. [INVARIANT_4] ФРАКТАЛЬНЫЙ ЛИМИТ. Длина модуля строго < 300 строк. При превышении — принудительная декомпозиция. [INVARIANT_5] НЕПРИКОСНОВЕННОСТЬ ЯКОРЕЙ. Блоки `[DEF]...[/DEF]` используются как аккумуляторы внимания. Закрывающий тег обязателен. -## II. СИНТАКСИС И РАЗМЕТКА (SEMANTIC ANCHORS) +## III. SYNTAX AND MARKUP (SEMANTIC ANCHORS) Формат зависит от среды исполнения: -- Python: `#[DEF:id:Type] ... # [/DEF:id:Type]` -- Svelte (HTML/Markup): ` ... ` -- Svelte (Script/JS): `// [DEF:id:Type] ... //[/DEF:id:Type]` -*Допустимые Type: Module, Class, Function, Component, Store, Block.* +- Markdown / docs: `# [DEF:Id:Type] ... # [/DEF:Id:Type]` +- Python: `# [DEF:Id:Type] ... # [/DEF:Id:Type]` +- Svelte (HTML/Markup): ` ... ` +- Svelte (Script/JS/TS): `// [DEF:Id:Type] ... // [/DEF:Id:Type]` +*Допустимые Type: Root, Standard, Module, Class, Function, Component, Store, Block.* **Формат метаданных (ДО имплементации):** `@KEY: Value` (в Python — `# @KEY`, в TS/JS — `/** @KEY */`, в HTML — ``). @@ -28,7 +68,7 @@ `@RELATION: [PREDICATE] ->[TARGET_ID]` *Допустимые предикаты:* DEPENDS_ON, CALLS, INHERITS, IMPLEMENTS, DISPATCHES, BINDS_TO. -## III. ТОПОЛОГИЯ ФАЙЛА (СТРОГИЙ ПОРЯДОК) +## IV. FILE TOPOLOGY (STRICT ORDER) 1. **HEADER (Заголовок):**[DEF:filename:Module] @COMPLEXITY: [1|2|3|4|5] *(алиас: `@C:`)* @SEMANTICS: [keywords] @@ -39,7 +79,7 @@ 2. **BODY (Тело):** Импорты -> Реализация логики внутри вложенных `[DEF]`. 3. **FOOTER (Подвал):** [/DEF:filename:Module] -## IV. КОНТРАКТЫ (DESIGN BY CONTRACT & UX) +## V. CONTRACTS (DESIGN BY CONTRACT & UX) Контракты требуются адаптивно по уровню сложности, а не по жесткому tier. **[CORE CONTRACTS]:** @@ -62,7 +102,7 @@ - `@TEST_EDGE: [Название] ->[Сбой]` (Минимум 3: missing_field, invalid_type, external_fail). - `@TEST_INVARIANT: [Имя] -> VERIFIED_BY: [scenario_1, ...]` -## V. ШКАЛА СЛОЖНОСТИ (COMPLEXITY 1-5) +## VI. COMPLEXITY SCALE (1-5) Степень контроля задается в Header через `@COMPLEXITY` или сокращение `@C`. Если тег отсутствует, сущность по умолчанию считается **Complexity 1**. Это сделано специально для экономии токенов и снижения шума на очевидных утилитах. @@ -93,7 +133,7 @@ - Использование `belief_scope` строго обязательно. -## VI. ПРОТОКОЛ ЛОГИРОВАНИЯ (THREAD-LOCAL BELIEF STATE) +## VII. LOGGING PROTOCOL (THREAD-LOCAL BELIEF STATE) Логирование — это механизм трассировки рассуждений ИИ (CoT) и управления Attention Energy. Архитектура использует Thread-local storage (`_belief_state`), поэтому `ID` прокидывается автоматически. **[PYTHON CORE TOOLS]:** @@ -113,7 +153,7 @@ *(Для Frontend/Svelte использовать ручной префикс: `console.info("[ID][REFLECT] Text", {data})`)* -## VII. АЛГОРИТМ ИСПОЛНЕНИЯ И САМОКОРРЕКЦИИ +## VIII. EXECUTION AND SELF-CORRECTION FLOW **[PHASE_1: ANALYSIS]** Оцени Complexity, Layer и UX-требования. При слепоте контекста -> `yield [NEED_CONTEXT: id]`. **[PHASE_2: SYNTHESIS]** @@ -129,11 +169,13 @@ 2. ГИПОТЕЗА: Сгенерируй вызов `logger.explore("Ошибка в I/O / Состоянии / Зависимости -> Описание")`. 3. ЗАПРОС: Запроси разрешение на изменение контракта. -## VIII. ТЕСТЫ: ПРАВИЛА РАЗМЕТКИ +## IX. TEST MARKUP RULES Для предотвращения перегрузки тестовых файлов семантическим шумом и снижения "orphan count" применяются упрощенные правила: 1. **Короткие ID:** Тестовые модули ОБЯЗАНЫ иметь короткие семантические ID (например, `AssistantApiTests`), а не полные пути импорта. 2. **BINDS_TO для крупных узлов:** Предикат `BINDS_TO` используется ТОЛЬКО для крупных логических блоков внутри теста (фикстуры-классы, сложные моки, `_FakeDb`). 3. **Complexity 1 для хелперов:** Мелкие вспомогательные функции внутри теста (`_run_async`, `_setup_mock`) остаются на уровне Complexity 1. Для них `@RELATION` и `@PURPOSE` не требуются — достаточно якорей `[DEF]...[/DEF]`. 4. **Тестовые сценарии:** Сами функции тестов (`test_...`) по умолчанию считаются Complexity 2 (требуется только `@PURPOSE`). Использование `BINDS_TO` для них опционально. -5. **Запрет на цепочки:** Не нужно описывать граф вызовов внутри теста. Достаточно "заземлить" 1-2 главных хелпера на ID модуля через `BINDS_TO`, чтобы файл перестал считаться набором сирот. \ No newline at end of file +5. **Запрет на цепочки:** Не нужно описывать граф вызовов внутри теста. Достаточно "заземлить" 1-2 главных хелпера на ID модуля через `BINDS_TO`, чтобы файл перестал считаться набором сирот. + +# [/DEF:Std:Semantics:Standard] diff --git a/.ai/standards/ui_design.md b/.ai/standards/ui_design.md index b74087a6..405b2fcd 100644 --- a/.ai/standards/ui_design.md +++ b/.ai/standards/ui_design.md @@ -41,8 +41,8 @@ Each Svelte file must follow this structure: */ import { ... } from "..."; - // Exports (Props) - export let prop_name = "..."; + // Props + const { prop_name = "..." } = $props(); // Logic @@ -72,4 +72,4 @@ Each Svelte file must follow this structure: * Ensure proper ARIA roles and keyboard navigation for interactive elements. * Use semantic HTML tags (`