# ss-tools Constitution

Конституция не дублирует правила — она объясняет, **почему** каждый принцип важен, и указывает, **где** искать полные инструкции.

## Core Principles

### I. Semantic Contract First

Каждая единица кода (функция, класс, модуль, компонент) должна быть аннотирована GRACE-Poly контрактом. Без контракта код невидим для семантического индекса, непроверяем агентом и недоступен для impact analysis.

**Немедленные правила** → [ADR-0002](docs/adr/ADR-0002-semantic-protocol.md)  
**Синтаксис и уровни сложности** → `skill({name="semantics-core"})`  
**Методология контрактов** → `skill({name="semantics-contracts"})`

### II. Decision Memory

Каждый архитектурный выбор, отвергающий альтернативу, должен быть записан: `@RATIONALE` (почему выбран этот путь) и `@REJECTED` (что запрещено и почему). Без этого агенты переоткрывают уже исследованные тупики, а долгоживущие сессии накапливают невидимый архитектурный дрейф.

**Протокол ADR** → `skill({name="semantics-contracts"})` §I  
**Каталог решений** → [`docs/adr/`](docs/adr/)  
**Правило запрета воскрешения**: silently reintroducing `@REJECTED` pattern = fatal regression. Требуется `<ESCALATION>`.

### III. External Orchestrator

ss-tools — внешний оркестратор над Apache Superset, а не плагин внутри него. Это даёт: независимый релизный цикл, отсутствие связанности с миграциями Superset, изоляцию DevOps-привилегий от BI-привилегий.

**Полное обоснование** → [ADR-0003](docs/adr/ADR-0003-orchestrator-pattern.md)

### IV. Module Discipline

Файл >400 строк или функция с цикломатической сложностью >10 — сигнал к декомпозиции. Каноническая структура директорий исключает циклические импорты и путаницу агентов при длинных speckit-сессиях.

**Структура и границы** → [ADR-0001](docs/adr/ADR-0001-module-layout.md)

### V. RBAC Enforcement

Все мутирующие операции требуют явной проверки роли. DevOps-привилегии (деплой, миграция, maintenance) отделены от BI-привилегий (просмотр дашбордов). Default-allow запрещён.

**Модель ролей и паттерны** → [ADR-0005](docs/adr/ADR-0005-auth-rbac.md)

### VI. Frontend — Svelte 5 Runes Only

Только runes-синтаксис (`$state`, `$derived`, `$effect`, `$props`). Устаревший синтаксис Svelte 4 создаёт путаницу и баги реактивности. `fromStore` + несколько `$derived` вызывают бесконечный reactive flush loop — задокументированный отказ.

**Архитектура фронтенда** → [ADR-0006](docs/adr/ADR-0006-frontend-architecture.md)  
**Запрет fromStore+$derived** → [ADR-0007](docs/adr/ADR-0007-rejected-fromStore-derived.md)  
**Паттерны компонентов** → `skill({name="semantics-svelte"})`

### VII. Test-Driven for C3+ Contracts

Контракты уровня C3 и выше требуют тестов, написанных до реализации. Тесты верифицируют `@PRE`/`@POST`/`@INVARIANT`, а не детали реализации. Минимум один тест должен явно проверять, что `@REJECTED` путь производит ожидаемый отказ.

**Методология тестирования** → `skill({name="semantics-testing"})`

## Development Workflow

```text
/speckit.specify → /speckit.clarify → /speckit.plan → /speckit.tasks → /speckit.implement
```

- Ни один этап не пропускается при наличии `[NEEDS CLARIFICATION]`
- Мутация контрактов: preview → apply, никогда сразу apply
- Все артефакты фичи — в `specs/<feature>/`, никогда в `.kilo/` или `.ai/`

## Verification Gates

| Gate | Команда |
|------|---------|
| Backend tests | `cd backend && source .venv/bin/activate && python -m pytest -v` |
| Frontend tests | `cd frontend && npm run test` |
| Backend lint | `cd backend && python -m ruff check .` |
| Frontend lint | `cd frontend && npm run lint` |
| Semantic audit | `axiom_semantic_validation audit_contracts` |

## Governance

Конституция имеет приоритет над всеми остальными практиками разработки. Изменения требуют: документирования предложения, проверки на согласованность со всеми ADR, плана миграции затронутого кода, и bump версии.

**Version**: 1.0.0 | **Ratified**: 2026-05-22 | **Last Amended**: 2026-05-22