busya
d9669698b8
Spec: 5 user stories (P1-P3), 17 FRs, 7 SCs, 12 edge cases, RBAC matrix Plan: 7 research decisions, 15 semantic contracts (C1-C4) Data: 4 SQLAlchemy models (Banner entity enforces one-chart-per-dashboard) UX: async-only API, banner template with optional variables, admin settings UI Tasks: 64 tasks across 8 phases, 12 reused frontend components Workflow: component reuse scan mandated in speckit.plan/tasks + semantics-svelte Constitution: filled with 7 architecture principles from ADRs
80 lines
5.5 KiB
Markdown
80 lines
5.5 KiB
Markdown
# 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
|