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
5.5 KiB
ss-tools Constitution
Конституция не дублирует правила — она объясняет, почему каждый принцип важен, и указывает, где искать полные инструкции.
Core Principles
I. Semantic Contract First
Каждая единица кода (функция, класс, модуль, компонент) должна быть аннотирована GRACE-Poly контрактом. Без контракта код невидим для семантического индекса, непроверяем агентом и недоступен для impact analysis.
Немедленные правила → ADR-0002
Синтаксис и уровни сложности → skill({name="semantics-core"})
Методология контрактов → skill({name="semantics-contracts"})
II. Decision Memory
Каждый архитектурный выбор, отвергающий альтернативу, должен быть записан: @RATIONALE (почему выбран этот путь) и @REJECTED (что запрещено и почему). Без этого агенты переоткрывают уже исследованные тупики, а долгоживущие сессии накапливают невидимый архитектурный дрейф.
Протокол ADR → skill({name="semantics-contracts"}) §I
Каталог решений → docs/adr/
Правило запрета воскрешения: silently reintroducing @REJECTED pattern = fatal regression. Требуется <ESCALATION>.
III. External Orchestrator
ss-tools — внешний оркестратор над Apache Superset, а не плагин внутри него. Это даёт: независимый релизный цикл, отсутствие связанности с миграциями Superset, изоляцию DevOps-привилегий от BI-привилегий.
Полное обоснование → ADR-0003
IV. Module Discipline
Файл >400 строк или функция с цикломатической сложностью >10 — сигнал к декомпозиции. Каноническая структура директорий исключает циклические импорты и путаницу агентов при длинных speckit-сессиях.
Структура и границы → ADR-0001
V. RBAC Enforcement
Все мутирующие операции требуют явной проверки роли. DevOps-привилегии (деплой, миграция, maintenance) отделены от BI-привилегий (просмотр дашбордов). Default-allow запрещён.
Модель ролей и паттерны → ADR-0005
VI. Frontend — Svelte 5 Runes Only
Только runes-синтаксис ($state, $derived, $effect, $props). Устаревший синтаксис Svelte 4 создаёт путаницу и баги реактивности. fromStore + несколько $derived вызывают бесконечный reactive flush loop — задокументированный отказ.
Архитектура фронтенда → ADR-0006
Запрет fromStore+$derived → ADR-0007
Паттерны компонентов → skill({name="semantics-svelte"})
VII. Test-Driven for C3+ Contracts
Контракты уровня C3 и выше требуют тестов, написанных до реализации. Тесты верифицируют @PRE/@POST/@INVARIANT, а не детали реализации. Минимум один тест должен явно проверять, что @REJECTED путь производит ожидаемый отказ.
Методология тестирования → skill({name="semantics-testing"})
Development Workflow
/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