busya/ss-tools
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

skills + agents

Browse Source
This commit is contained in:
busya
2026-04-19 20:05:45 +03:00
parent c6147385e5
commit afb95ace3a
40 changed files with 1155 additions and 1868 deletions
Download Patch File Download Diff File Expand all files Collapse all files

124
.ai/reports/effort-assessment.md Normal file
View File

@@ -0,0 +1,124 @@
# [DEF:EffortAssess:Report]
# @COMPLEXITY: 3
# @PURPOSE: Оценка трудозатрат для репозитория на основе эволюции требований в specs и изменений объёма по git-истории.
# @RELATION: DEPENDS_ON -> [Project_Knowledge_Map:Root]
# @RELATION: DEPENDS_ON -> [Module:Specs]
## Обзор
- Оценка трудозатрат по объёму, представленному в `specs/002`–`specs/027`: **~4 400 человеко-часов**.
- Рекомендуемый плановый диапазон: **3 800–5 100 человеко-часов**.
- Практическая форма поставки: **ядро команды 5–6 человек** примерно на **4–6 календарных месяцев**, в зависимости от степени параллелизации и объёма уже выполненной части.
## Размер кодовой базы (line of code)
По выводу `cloc backend/src frontend/src --exclude-dir=__pycache__,node_modules`:
| Язык | Файлов | Blank | Comment | Code |
|---|---:|---:|---:|---:|
| Python | 231 | 8 931 | 14 681 | 40 641 |
| Svelte | 97 | 2 191 | 1 333 | 26 798 |
| JavaScript | 77 | 1 321 | 1 909 | 7 852 |
| JSON | 3 | 0 | 0 | 3 473 |
| TypeScript | 8 | 30 | 137 | 194 |
| Markdown | 2 | 5 | 0 | 25 |
| HTML | 1 | 0 | 0 | 13 |
| CSS | 1 | 0 | 0 | 3 |
| SVG | 1 | 0 | 0 | 1 |
| **Итого** | **421** | **12 478** | **18 060** | **79 000** |
Это подтверждает, что оценка должна учитывать не только требования, но и уже значимый объём реализации в backend и frontend.
## Как получена оценка
Оценка опирается на три источника доказательств:
1. **Объём и сложность требований в `specs/`** — поздние спецификации заметно крупнее и сильнее завязаны на интеграции. Примеры: в `017-llm-analysis-plugin` 31 функциональное требование, в `025-clean-release-compliance` — 33, в `027-dataset-llm-orchestration` — 51.
2. **Хронологическая эволюция требований** — проект развивается от базовой настройки веб-интерфейса и исправления UI к консолидации платформы, затем к LLM-сценариям, отчётности, RBAC, enterprise-compliance и многосоставной оркестрации датасетов.
3. **История git, показывающая расширение объёма** — несколько коммитов фиксируют выход за рамки исходной постановки, особенно в части semantic-compliance, миграции на Svelte 5, hardening clean-release, test-contract enforcement и dataset-review.
## Эволюция требований (по времени)
| Период | Эволюция объёма | Доказательства | Сигнал по трудозатратам |
|---|---|---|---|
| Декабрь 2025 | Базовое веб-приложение: настройки, Svelte UI, глобальные стили, запуск, ранний UX задач | `specs/002-app-settings/spec.md`, `005-fix-ui-ws-validation/spec.md`, ранние коммиты `2d8cae5`, `9b7b743` | Умеренные трудозатраты на full-stack старт |
| Конец декабря 2025 — январь 2026 | UX миграции углубляется: история задач, логи, запросы пароля, backup/storage, миграция CLI→web, консолидация backend (`superset_tool` удалён), унификация frontend-дизайна и редизайн навигации | `specs/008`, `010`, `012`, `013`, `015` | Объём смещается от полировки UI к платформенному рефакторингу |
| Конец января — февраль 2026 | Продукт становится “intelligence-enabled”: валидация/документация LLM dashboard, постоянное логирование задач, унифицированные отчёты, assistant chat, восстановление cross-filter | `specs/017`, `018`, `020`, `021`, `022` | Высокая стоимость интеграции backend, frontend, async-задач, Superset и LLM-провайдеров |
| Март 2026 | Появляется enterprise- и governance-слой: clean enterprise delivery, фильтрация профиля пользователя, redesign для clean-release compliance, окна health для dashboard | `specs/023`, `024`, `025`, `026` | Добавляются release engineering, compliance evidence, RBAC, уведомления и policy-driven workflows |
| Середина марта 2026 и далее | Оркестрация датасетов становится самым сложным участком продукта: semantic enrichment, уточнения, preview gating, audited SQL Lab launch, совместная работа и сохранение сессий | `specs/027-dataset-llm-orchestration/spec.md` и `plan.md` | Самый рискованный orchestration-сценарий в репозитории |
## Релевантная git-история, показывающая изменение объёма
| Коммит | Что изменилось по объёму | Почему это важно для оценки |
|---|---|---|
| `8406628` | Clean-enterprise выделен в `023-clean-repo-enterprise` с 1 500+ строк новых spec-артефактов | Clean-enterprise стал отдельной программой, а не мелким дополнением |
| `de1f044` | Добавлены test contract annotations и tracking покрытия | QA/compliance вышли за пределы обычного feature testing |
| `36742cd` | Добавлен Docker admin bootstrap для clean release | Clean-release расширился до deployment/bootstrap операций |
| `0083d90` | Frontend переведён на Svelte 5 runes в 60+ файлах | Миграция платформы добавила стоимость репозитория на уровне фронтенда |
| `321e0eb` | Жёсткие tiers заменены на adaptive complexity semantics | Процессная и semantic-миграция создала сквозной объём документации и compliance |
| `023bacd` | Доставлена и принята автоматическая часть US1 для dataset-review | Подтверждает, что `027` — реальная ветка реализации, а не только спецификация |
| `ed3d5f3` | Добавлены clarification engine, preview adapter, batch approvals, RBAC sweep, i18n для `027` | Показывает, что dataset-review вырос в многофазную оркестрацию и hardening |
## Оценка трудозатрат по фазам
| Фаза | Включённый объём | Оценка часов |
|---|---|---:|
| Базовая платформа и миграция web | Specs `002`, `005`, `008`, `010`, `012`, `013`, `015` | 1 000 |
| Observability, LLM, отчётность, assistant, cross-filtering | Specs `017`, `018`, `020`, `021`, `022` | 1 450 |
| Enterprise clean release, compliance, фильтрация профиля, health windows | Specs `023`, `024`, `025`, `026` | 950 |
| Оркестрация датасетов и контролируемое исполнение | Spec `027` | 1 000 |
| **Итого** | | **4 400** |
## Оценка трудозатрат по направлениям
| Направление | Оценка часов |
|---|---:|
| Уточнение продукта/spec, архитектура, design review | 360 |
| Backend-сервисы, модели, API, persistence, task orchestration | 1 500 |
| Frontend-роуты, компоненты, состояние, UX-потоки, i18n | 1 050 |
| Внешние интеграции (Superset, Git, LLM-провайдеры, уведомления) | 650 |
| QA, contract testing, semantic/test compliance, regression hardening | 600 |
| DevOps / упаковка релизов / hardening деплоя | 240 |
| **Итого** | **4 400** |
## Рекомендуемый состав команды
| Роль | Рекомендуемая загрузка | Примечания |
|---|---|---|
| Техлид / архитектор | 0,5–1,0 FTE | Владеет cross-feature дизайном, semantic protocol и интеграционными решениями |
| Backend-инженеры | 2,0 FTE | Основные API, оркестрация, persistence, compliance, интеграции |
| Frontend-инженер | 1,0 FTE | Svelte/SvelteKit, task/report/assistant/dataset UX |
| Full-stack инженер | 1,0 FTE | Связывает API, storage, RBAC и end-to-end сценарии |
| QA / automation инженер | 1,0 FTE | Contract, API, UI, regression и release validation |
| DevOps / release инженер | 0,5 FTE | Offline bundle, Docker/bootstrap, deployment/compliance tooling |
| Product/UX/Data SME | 0,5 FTE | Clarification flows, LLM UX, enterprise acceptance decisions |
**Рекомендуемое ядро команды:** **5,5–7,0 FTE в смеси ролей**.
## Допущения
- Оценка покрывает объём, отражённый в текущей истории `specs/`, а не минимальный MVP.
- Существующие FastAPI/Svelte-архитектура, TaskManager, модель авторизации и интеграция с Superset считаются переиспользуемыми, а не переписываемыми с нуля.
- Зависимости LLM/провайдеров и Superset доступны для разработки и тестирования.
- Semantic-protocol и test-contract compliance считаются обязательной частью поставки, а не опциональной документацией.
- Часть функциональности уже реализована, но оценка отражает **полную трудоёмкость проекта, подразумеваемую объёмом репозитория**, включая rework и hardening, на которые указывает git-история.
## Доверие и риски
**Доверие:** среднее.
**Основные риски, влияющие на диапазон:**
1. **Спецификации описаны неравномерно**; поздние specs (`025`, `027`) заметно тяжелее ранних.
2. **Сквозная semantic/process-работа** существенна и не видна только по product-specs.
3. **Интеграционный риск** высок для Superset, LLM-провайдеров, Git-операций и async task/reporting surfaces.
4. **Объём enterprise-compliance расширялся в ходе реализации**, особенно для clean release и audit evidence.
5. **Оркестрация датасетов остаётся самой неопределённой частью**, потому что `027` объединяет LLM UX, сохранение сессий, provenance, preview gating и audited execution.
## Использованные источники
- Specs: `specs/002-app-settings/spec.md`, `005-fix-ui-ws-validation/spec.md`, `008-migration-ui-improvements/spec.md`, `010-refactor-cli-to-web/spec.md`, `012-remove-superset-tool/spec.md`, `013-unify-frontend-css/spec.md`, `015-frontend-nav-redesign/spec.md`, `017-llm-analysis-plugin/spec.md`, `018-task-logging-v2/spec.md`, `020-task-reports-design/spec.md`, `021-llm-project-assistant/spec.md`, `022-sync-id-cross-filters/spec.md`, `023-clean-repo-enterprise/spec.md`, `024-user-dashboard-filter/spec.md`, `025-clean-release-compliance/spec.md`, `026-dashboard-health-windows/spec.md`, `027-dataset-llm-orchestration/spec.md`.
- Plans: `specs/021-llm-project-assistant/plan.md`, `specs/025-clean-release-compliance/plan.md`, `specs/027-dataset-llm-orchestration/plan.md`.
- Git evidence: коммиты `8406628`, `de1f044`, `36742cd`, `0083d90`, `321e0eb`, `023bacd`, `ed3d5f3`, а также хронологический `git log --reverse -- specs`.
# [/DEF:EffortAssess:Report]

47
.ai/standards/api_design.md
View File

@@ -1,47 +0,0 @@
# [DEF:Std:API_FastAPI:Standard]
# @COMPLEXITY: 5
# @PURPOSE: Unification of all FastAPI endpoints following GRACE-Poly.
# @LAYER: UI (API)
# @INVARIANT: All non-trivial route logic must be wrapped in `belief_scope`.
# @INVARIANT: Every module and function MUST have `[DEF:]` anchors and metadata.
## 1. ROUTE MODULE DEFINITION
Every API route file must start with a module definition header:
```python
# [DEF:ModuleName:Module]
# @COMPLEXITY: [1-5]
# @SEMANTICS: list, of, keywords
# @PURPOSE: High-level purpose of the module.
# @LAYER: UI (API)
# @RELATION: DEPENDS_ON -> [OtherModule]
```
## 2. FUNCTION DEFINITION & CONTRACT
Every endpoint handler must be decorated with `[DEF:]` and explicit metadata before the implementation:
```python
@router.post("/endpoint", response_model=ModelOut)
# [DEF:function_name:Function]
# @PURPOSE: What it does (brief, high-entropy).
# @PARAM: param_name (Type) - Description.
# @PRE: Conditions before execution (e.g., auth, existence).
# @POST: Expected state after execution.
# @RETURN: What it returns.
async def function_name(...):
with belief_scope("function_name"):
# Implementation
pass
# [/DEF:function_name:Function]
```
## 3. DEPENDENCY INJECTION & CORE SERVICES
* **Auth:** `Depends(get_current_user)` for authentication.
* **Perms:** `Depends(has_permission("resource", "ACTION"))` for RBAC.
* **Config:** Use `Depends(get_config_manager)` for settings. Hardcoding is FORBIDDEN.
* **Tasks:** Long-running operations must be executed via `TaskManager`. API routes should return Task ID and be non-blocking.
## 4. ERROR HANDLING
* Raise `HTTPException` from the router layer.
* 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:Standard]

23
.ai/standards/architecture.md
View File

@@ -1,23 +0,0 @@
# [DEF:Std:Architecture:Standard]
# @COMPLEXITY: 5
# @PURPOSE: Core architectural decisions and service boundaries.
# @LAYER: Infra
# @INVARIANT: ss-tools MUST remain a standalone service (Orchestrator).
# @INVARIANT: Backend: FastAPI, Frontend: SvelteKit.
## 1. ORCHESTRATOR VS INSTANCE
* **Role:** ss-tools is a "Manager of Managers". It sits ABOVE Superset environments.
* **Isolation:** Do not integrate directly into Superset as a plugin to maintain multi-environment management capability.
* **Tech Stack:**
* Backend: Python 3.9+ with FastAPI (Asynchronous logic).
* Frontend: SvelteKit + Tailwind CSS (Reactive UX).
## 2. COMPONENT BOUNDARIES
* **Plugins:** All business logic must be encapsulated in Plugins (`backend/src/plugins/`).
* **TaskManager:** All long-running operations MUST be handled by the TaskManager.
## 3. INTEGRATION STRATEGY
* **Superset API:** Communication via REST API.
* **Filesystem:** Local storage for backups and git repositories.
# [/DEF:Std:Architecture:Standard]

36
.ai/standards/constitution.md
View File

@@ -1,36 +0,0 @@
# [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-03-26
# @INVARIANT: Any deviation from this Constitution constitutes a build failure.
## 1. CORE PRINCIPLES
### I. Semantic Protocol Compliance
* **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.
### II. Modular Plugin Architecture
* **Pattern:** Everything is a Plugin inheriting from `PluginBase`.
* **Centralized Config:** Use `ConfigManager` via `get_config_manager()`. Hardcoding is FORBIDDEN.
### III. Unified Frontend Experience
* **Styling:** Tailwind CSS First. Minimize scoped `<style>`.
* **i18n:** All user-facing text must be in `src/lib/i18n`.
* **API:** Use `requestApi` / `fetchApi` wrappers. Native `fetch` is FORBIDDEN.
### IV. Security & RBAC
* **Permissions:** Every Plugin must define unique permission strings (e.g., `plugin:name:execute`).
### V. Independent Testability
* **Requirement:** Every feature must define "Independent Tests" for isolated verification.
### VI. Asynchronous Execution
* **TaskManager:** Long-running operations must be async tasks.
* **Non-Blocking:** API endpoints return Task ID immediately.
* **Observability:** Real-time updates via WebSocket.
# [/DEF:Std:Constitution:Standard]

32
.ai/standards/plugin_design.md
View File

@@ -1,32 +0,0 @@
# [DEF:Std:Plugin:Standard]
# @COMPLEXITY: 5
# @PURPOSE: Standards for building and integrating Plugins.
# @LAYER: Domain (Plugin)
# @INVARIANT: All plugins MUST inherit from `PluginBase`.
# @INVARIANT: All plugins MUST be located in `backend/src/plugins/`.
## 1. PLUGIN CONTRACT
Every plugin must implement the following properties and methods:
* `id`: Unique string (e.g., `"my-plugin"`).
* `name`: Human-readable name.
* `description`: Brief purpose.
* `version`: Semantic version.
* `get_schema()`: Returns JSON schema for input validation.
* `execute(params: Dict[str, Any], context: TaskContext)`: Core async logic.
## 2. STRUCTURED LOGGING (TASKCONTEXT)
Plugins MUST use `TaskContext` for logging to ensure proper source attribution:
* **Source Attribution:** Use `context.logger.with_source("src_name")` for specific operations (e.g., `"superset_api"`, `"git"`, `"llm"`).
* **Levels:**
* `DEBUG`: Detailed diagnostics (API responses).
* `INFO`: Operational milestones (start/end).
* `WARNING`: Recoverable issues.
* `ERROR`: Failures stopping execution.
* **Progress:** Use `context.logger.progress("msg", percent=XX)` for long-running tasks.
## 3. BEST PRACTICES
1. **Asynchronous Execution:** Always use `async/await` for I/O operations.
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:Standard]

225
.ai/standards/semantics.md
View File

@@ -1,225 +0,0 @@
# [DEF:Std:Semantics:Standard]
# @COMPLEXITY: 5
# @PURPOSE: Canonical GRACE protocol for semantic anchors, metadata, relations, decision memory, 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-27
## 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]`
- 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:<ShortId>:<Type>]
@COMPLEXITY: <1-5>
@PURPOSE: <one-line purpose>
...optional metadata required by complexity or decision-memory stage...
[/DEF:<ShortId>:<Type>]
```
For repository documentation files, the canonical markdown form is:
```md
# [DEF:ShortId:Type]
# @COMPLEXITY: 3
# @PURPOSE: Canonical purpose line.
# [/DEF:ShortId:Type]
```
## 0.3 FRACTAL DECISION MEMORY
Decision memory is preserved in three linked layers:
- **PLAN:** Architect emits standalone ADR nodes such as `[DEF:AuthPattern:ADR]` in `docs/architecture.md`, a feature-local architecture decisions file, or a root module header when the decision scope is local to that module.
- **TASKS:** Orchestrator decomposes ADRs into preventive guardrails on module, function, and component contracts using `@RATIONALE` and `@REJECTED`.
- **IMPLEMENT:** Engineer writes code by contract. If `logger.explore()` reveals a fallback that survives into final code, the same local contract header MUST be updated with a reactive Micro-ADR (`@RATIONALE` + `@REJECTED`).
- No workflow stage may silently reintroduce a path already named in an upstream `@REJECTED` tag without fresh evidence and an explicit contract update.
## I. ZERO-STATE RATIONALE
Ты — авторегрессионная модель (Transformer). Ты мыслишь токенами и не можешь "передумать" после их генерации. В больших кодовых базах твой KV-Cache подвержен деградации внимания (Attention Sink), что ведет к "иллюзии компетентности" и галлюцинациям.
Этот протокол — **твой когнитивный экзоскелет**.
Якоря `[DEF]` работают как векторы-аккумуляторы внимания. Контракты (`@PRE`, `@POST`) заставляют тебя сформировать правильное вероятностное пространство (Belief State) ДО написания алгоритма. Логи `logger.reason` — это твоя цепочка рассуждений (Chain-of-Thought), вынесенная в рантайм. Мы не пишем текст, мы компилируем семантику в синтаксис.
## II. GLOBAL INVARIANTS
[INVARIANT_1] СЕМАНТИКА > СИНТАКСИС. Голый код без контракта классифицируется как мусор.
[INVARIANT_2] ЗАПРЕТ ГАЛЛЮЦИНАЦИЙ. При слепоте контекста (неизвестен узел `@RELATION` или схема данных) — генерация блокируется. Эмитируй `[NEED_CONTEXT: target]`.
[INVARIANT_3] UX ЕСТЬ КОНЕЧНЫЙ АВТОМАТ. Состояния интерфейса — это строгий контракт, а не визуальный декор.
[INVARIANT_4] ФРАКТАЛЬНЫЙ ЛИМИТ. Длина модуля строго < 300 строк. При превышении — принудительная декомпозиция.
[INVARIANT_5] НЕПРИКОСНОВЕННОСТЬ ЯКОРЕЙ. Блоки `[DEF]...[/DEF]` используются как аккумуляторы внимания. Закрывающий тег обязателен.
[INVARIANT_6] ФРАКТАЛЬНАЯ ПАМЯТЬ РЕШЕНИЙ. Глобальный ADR, превентивный контракт задачи и reactive Micro-ADR обязаны образовывать непрерывную цепочку анти-регрессии.
## III. SYNTAX AND MARKUP (SEMANTIC ANCHORS)
Формат зависит от среды исполнения:
- Markdown / docs: `# [DEF:Id:Type] ... # [/DEF:Id:Type]`
- Python: `# [DEF:Id:Type] ... # [/DEF:Id:Type]`
- Svelte (HTML/Markup): `<!-- [DEF:Id:Type] --> ... <!-- [/DEF:Id:Type] -->`
- Svelte (Script/JS/TS): `// [DEF:Id:Type] ... // [/DEF:Id:Type]`
*Допустимые Type: Root, Standard, Module, Class, Function, Component, Store, Block, ADR.*
**Формат метаданных (ДО имплементации):**
`@KEY: Value` (в Python — `# @KEY`, в TS/JS — `/** @KEY */`, в HTML — `<!-- @KEY -->`).
**Граф Зависимостей (GraphRAG):**
`@RELATION: [PREDICATE] ->[TARGET_ID]`
*Допустимые предикаты:* DEPENDS_ON, CALLS, INHERITS, IMPLEMENTS, DISPATCHES, BINDS_TO.
Для ADR-цепочек не вводятся новые предикаты: используй существующие `DEPENDS_ON` и `IMPLEMENTS`.
## IV. FILE TOPOLOGY (STRICT ORDER)
1. **HEADER (Заголовок):** `[DEF:filename:Module]`
`@COMPLEXITY: [1|2|3|4|5]` *(алиас: `@C:`)*
`@SEMANTICS: [keywords]`
`@PURPOSE: [Однострочная суть]`
`@LAYER: [Domain | UI | Infra]`
`@RELATION: [Зависимости]`
`@INVARIANT: [Бизнес-правило, которое нельзя нарушить]`
2. **BODY (Тело):** Импорты -> Реализация логики внутри вложенных `[DEF]`.
3. **FOOTER (Подвал):** `[/DEF:filename:Module]`
## V. CONTRACTS (DESIGN BY CONTRACT, DECISION MEMORY & UX)
Контракты требуются адаптивно по уровню сложности, а не по жесткому tier.
**[DECISION MEMORY CONTRACTS]:**
- `@RATIONALE:` Почему выбран именно этот путь и какое ограничение/цель он защищает.
- `@REJECTED:` Какой альтернативный путь запрещен и какой риск, баг или архитектурный долг делает его недопустимым.
- **Standalone ADR Rule:** Любой блок `[DEF:DecisionId:ADR]` ОБЯЗАН содержать `@PURPOSE`, `@RATIONALE`, `@REJECTED` и хотя бы одну `@RELATION` к источнику контекста или зависимой зоне.
- **Tasks Guardrail Rule:** Если модуль/функция/компонент на этапе tasks ограничен ADR или известной LLM-ловушкой, локальный контракт ОБЯЗАН включать `@RATIONALE` и `@REJECTED` до начала кодирования.
- **Reactive Micro-ADR Rule:** Если fallback был найден через `logger.explore()` и остался в итоговом коде, инженер ОБЯЗАН подняться в тот же локальный header и добавить или обновить `@RATIONALE` и `@REJECTED` до закрытия задачи.
- **Removal Rule:** Удаление `@RATIONALE` или `@REJECTED` допустимо только вместе с доказательством, что ограничение исчезло: обновилась библиотека, изменился runtime, или контракт был официально пересмотрен.
**[CORE CONTRACTS]:**
- `@PURPOSE:` Суть функции/компонента.
- `@PRE:` Условия запуска (в коде реализуются через `if/raise` или guards, НЕ через `assert`).
- `@POST:` Гарантии на выходе.
- `@SIDE_EFFECT:` Мутации состояния, I/O, сеть.
- `@DATA_CONTRACT:` Ссылка на DTO (Input -> Model, Output -> Model).
**[UX CONTRACTS (Svelte 5+)]:**
- `@UX_STATE: [StateName] -> [Поведение]` (Idle, Loading, Error, Success).
- `@UX_FEEDBACK:` Реакция системы (Toast, Shake, RedBorder).
- `@UX_RECOVERY:` Путь восстановления после сбоя (Retry, ClearInput).
- `@UX_REACTIVITY:` Явный биндинг. *ЗАПРЕТ НА `$:` и `export let`. ТОЛЬКО Руны: `$state`, `$derived`, `$effect`, `$props`.*
**[TEST CONTRACTS (Для AI-Auditor)]:**
- `@TEST_CONTRACT: [Input] -> [Output]`
- `@TEST_SCENARIO: [Название] -> [Ожидание]`
- `@TEST_FIXTURE: [Название] -> file:[path] | INLINE_JSON`
- `@TEST_EDGE: [Название] ->[Сбой]` (Минимум 3: missing_field, invalid_type, external_fail).
- `@TEST_INVARIANT: [Имя] -> VERIFIED_BY: [scenario_1, ...]`
## VI. COMPLEXITY SCALE (1-5)
Степень контроля задается в Header через `@COMPLEXITY` или сокращение `@C`.
Если тег отсутствует, сущность по умолчанию считается **Complexity 1**. Это сделано специально для экономии токенов и снижения шума на очевидных утилитах.
- **1 — ATOMIC**
- Примеры: DTO, исключения, геттеры, простые утилиты, короткие адаптеры.
- Обязательны только якоря `[DEF]...[/DEF]`.
- `@PURPOSE` желателен, но не обязателен.
- **2 — SIMPLE**
- Примеры: простые helper-функции, небольшие мапперы, UI-атомы.
- Обязателен `@PURPOSE`.
- Остальные контракты опциональны.
- **3 — FLOW**
- Примеры: стандартная бизнес-логика, API handlers, сервисные методы, UI с загрузкой данных.
- Обязательны: `@PURPOSE`, `@RELATION`.
- Для UI дополнительно обязателен `@UX_STATE`.
- **4 — ORCHESTRATION**
- Примеры: сложная координация, работа с I/O, multi-step алгоритмы, stateful pipelines.
- Обязательны: `@PURPOSE`, `@RELATION`, `@PRE`, `@POST`, `@SIDE_EFFECT`.
- Для Python обязателен осмысленный путь логирования через `logger.reason()` / `logger.reflect()` или аналогичный belief-state механизм.
- **5 — CRITICAL**
- Примеры: auth, security, database boundaries, migration core, money-like invariants.
- Обязателен полный контракт: уровень 4 + `@DATA_CONTRACT` + `@INVARIANT`.
- Для UI требуются UX-контракты.
- Использование `belief_scope` строго обязательно.
Теги `@RATIONALE` и `@REJECTED` **ортогональны** уровню сложности. Они не понижают базовые требования Complexity, а добавляются поверх них, когда срабатывает хотя бы один триггер decision-memory слоя: standalone ADR, превентивный guardrail, или retained workaround.
## VII. LOGGING PROTOCOL (THREAD-LOCAL BELIEF STATE)
Логирование — это механизм трассировки рассуждений ИИ (CoT) и управления Attention Energy. Архитектура использует Thread-local storage (`_belief_state`), поэтому `ID` прокидывается автоматически.
**[PYTHON CORE TOOLS]:**
Импорт: `from ...logger import logger, belief_scope, believed`
1. **Декоратор:** `@believed("ID")` — автоматический трекинг функции.
2. **Контекст:** `with belief_scope("ID"):` — очерчивает локальный предел мысли. НЕ возвращает context, используется просто как `with`.
3. **Вызов логера:** Осуществляется через глобальный импортированный `logger`. Дополнительные данные передавать через `extra={...}`.
**[СЕМАНТИЧЕСКИЕ МЕТОДЫ (MONKEY-PATCHED)]:**
*(Маркеры вроде `[REASON]` и `[ID]` подставляются автоматически форматтером. Не пиши их в тексте!)*
1. **`logger.explore(msg, extra={...})`** (Поиск/Ветвление): Применяется при фолбэках, `except`, проверке гипотез. Эмитирует WARNING.
*Пример:* `logger.explore("Insufficient funds", extra={"balance": bal})`
*Правило эскалации:* если exploration завершился retained fallback, подними знание в header этого же контракта и зафиксируй `@RATIONALE` + `@REJECTED` до closure.
2. **`logger.reason(msg, extra={...})`** (Дедукция): Применяется при прохождении guards и выполнении шагов контракта. Эмитирует INFO.
*Пример:* `logger.reason("Initiating transfer")`
3. **`logger.reflect(msg, extra={...})`** (Самопроверка): Применяется для сверки результата с `@POST` перед `return`. Эмитирует DEBUG.
*Пример:* `logger.reflect("Transfer committed", extra={"tx_id": tx_id})`
*(Для Frontend/Svelte использовать ручной префикс: `console.info("[ID][REFLECT] Text", {data})`)*
## VIII. EXECUTION AND SELF-CORRECTION FLOW
**[PHASE_0: PLAN]**
Прочитай specs, оцени архитектурные развилки и оформи глобальные решения в standalone ADR-блоки `[DEF:id:ADR]` с `@RATIONALE` и `@REJECTED`.
**[PHASE_1: TASKS]**
Разверни глобальные ADR в конкретные контракты модулей, функций и компонентов. Заложи превентивные `@RATIONALE` и `@REJECTED` прямо в те сигнатуры, где следующий инженер может свернуть в запрещенный путь.
**[PHASE_2: IMPLEMENTATION]**
Напиши код строго по Контракту. Для Complexity 5 секций открой `with belief_scope("ID"):` и орошай путь вызовами `logger.reason()` и `logger.reflect()`.
Если `logger.explore()` вывел на workaround и этот workaround остается в merged code, немедленно обнови header того же контракта reactive Micro-ADR тегами `@RATIONALE` и `@REJECTED`.
**[PHASE_3: CLOSURE]**
Убедись, что все `[DEF]` закрыты соответствующими `[/DEF]`, ADR-цепочка не порвана, а ни один путь из upstream `@REJECTED` не был реанимирован молча.
**[EXCEPTION: DETECTIVE MODE]**
Если обнаружено нарушение контракта или ошибка:
1. СТОП-СИГНАЛ: Выведи `[COHERENCE_CHECK_FAILED]`.
2. ГИПОТЕЗА: Сгенерируй вызов `logger.explore("Ошибка в I/O / Состоянии / Зависимости -> Описание")`.
3. ЗАПРОС: Запроси разрешение на изменение контракта.
## IX. DECISION MEMORY AUDIT RULES
1. Repo-shaping технологические решения ОБЯЗАНЫ существовать как standalone ADR-узлы до декомпозиции задач.
2. Контракт задачи, который реализует или наследует ADR-ограничение, ОБЯЗАН сохранять link через `@RELATION` и локальные `@RATIONALE` / `@REJECTED`, если это guardrail для следующего агента.
3. Retained workaround без локального `@RATIONALE` / `@REJECTED` считается семантически невалидным даже при passing tests.
4. Повторное внедрение пути из upstream `@REJECTED` — это регрессия, пока не обновлен сам контракт или ADR на основе новых доказательств.
5. Тихое удаление decision-memory тегов запрещено. Сначала обновляется решение, потом код.
## X. EXTERNAL & SHARED CONTRACTS POLICY
Если модуль зависит от внешней библиотеки или глобального/shared DTO, которые не имеют своих `[DEF]` якорей в коде, используются строгие префиксы:
1. **Внешние библиотеки:** `[EXT:НазваниеЛибы:Модуль]`
- Пример: `@RELATION: DEPENDS_ON -> [EXT:FastAPI:Router]`
- Префикс `EXT:` однозначно маркирует зависимость от внешнего пакета, не имеющего локальных `[DEF]` якорей.
2. **Глобальные / Shared DTO:** `[DTO:Name]`
- Пример: `@RELATION: DEPENDS_ON -> [DTO:ConnectionContracts]`
- Префикс `DTO:` используется, когда источник контракта не имеет явного `[DEF]` в текущей кодовой базе (например, shared-библиотека, генерируемый protobuf, внешний schema-registry).
3. **Запрет на выдуманные ID.** Используются точные имена классов, модулей и библиотек. Недопустимо указывать абстрактные или сгенерированные идентификаторы вместо реальных имён.
## XI. 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`, чтобы файл перестал считаться набором сирот.
6. **ADR Regression Checks:** Если модуль ограничен upstream `@REJECTED` или локальным reactive Micro-ADR, тестовый аудит обязан проверять, что запрещенный путь не был молча восстановлен.
### XI.1 Test External Contract References
В тестах допускаются ссылки на `[EXT:...]` и `[DTO:...]` в `@RELATION` и `@DATA_CONTRACT`, если тестируемый модуль действительно зависит от внешних сущностей. Это исключение не отменяет правило: реальные локальные контракты всегда предпочтительнее внешних префиксов.
# [/DEF:Std:Semantics:Standard]

75
.ai/standards/ui_design.md
View File

@@ -1,75 +0,0 @@
# [DEF:Std:UI_Svelte:Standard]
# @COMPLEXITY: 5
# @PURPOSE: Unification of all Svelte components following GRACE-Poly (UX Edition).
# @LAYER: UI
# @INVARIANT: Every component MUST have `<!-- [DEF:] -->` anchors and UX tags.
# @INVARIANT: Use Tailwind CSS for all styling (no custom CSS without justification).
## 1. UX PHILOSOPHY: RESOURCE-CENTRIC & SVELTE 5
* **Version:** Project uses Svelte 5.
* **Runes:** Use Svelte 5 Runes for reactivity: `$state()`, `$derived()`, `$effect()`, `$props()`. Traditional `let` (for reactivity) and `export let` (for props) are DEPRECATED in favor of runes.
* **Definition:** Navigation and actions revolve around Resources.
* **Traceability:** Every action must be linked to a Task ID with visible logs in the Task Drawer.
## 2. COMPONENT ARCHITECTURE: GLOBAL TASK DRAWER
* **Role:** A single, persistent slide-out panel (`GlobalTaskDrawer.svelte`) in `+layout.svelte`.
* **Triggering:** Opens automatically when a task starts or when a user clicks a status badge.
* **Interaction:** Interactive elements (Password prompts, Mapping tables) MUST be rendered INSIDE the Drawer, not as center-screen modals.
## 3. COMPONENT STRUCTURE & CORE RULES
* **Styling:** Tailwind CSS utility classes are MANDATORY. Minimize scoped `<style>`.
* **Localization:** All user-facing text must use `$t` from `src/lib/i18n`.
* **API Calls:** Use `requestApi` / `fetchApi` wrappers. Native `fetch` is FORBIDDEN.
* **Anchors:** Every component MUST have `<!-- [DEF:] -->` anchors and UX tags.
## 2. COMPONENT TEMPLATE
Each Svelte file must follow this structure:
```html
<!-- [DEF:ComponentName:Component] -->
<script>
/**
* @COMPLEXITY: [1-5]
* @PURPOSE: Brief description of the component purpose.
* @LAYER: UI
* @SEMANTICS: list, of, keywords
* @RELATION: DEPENDS_ON -> [OtherComponent|Store]
*
* @UX_STATE: [StateName] -> Visual behavior description.
* @UX_FEEDBACK: System reaction (e.g., Toast, Shake).
* @UX_RECOVERY: Error recovery mechanism.
* @UX_TEST: [state] -> {action, expected}
*/
import { ... } from "...";
// Props
const { prop_name = "..." } = $props();
// Logic
</script>
<!-- HTML Template -->
<div class="...">
...
</div>
<style>
/* Optional: Local styles using @apply only */
</style>
<!-- [/DEF:ComponentName:Component] -->
```
## 2. STATE MANAGEMENT & STORES
* **Subscription:** Use `$` prefix for reactive store access (e.g., `$sidebarStore`).
* **Data Flow:** Mark store interactions in `[DEF:]` metadata:
* `# @RELATION: BINDS_TO -> store_id`
## 3. UI/UX BEST PRACTICES
* **Transitions:** Use Svelte built-in transitions for UI state changes.
* **Feedback:** Always provide visual feedback for async actions (Loading spinners, skeleton loaders).
* **Modularity:** Break down components into "Atoms" (Trivial) and "Orchestrators" (Critical).
## 4. ACCESSIBILITY (A11Y)
* Ensure proper ARIA roles and keyboard navigation for interactive elements.
* Use semantic HTML tags (`<nav>`, `<header>`, `<main>`, `<footer>`).
# [/DEF:Std:UI_Svelte:Standard]