feat(031): Maintenance Banner for Dashboards — full spec→plan→tasks package
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
This commit is contained in:
@@ -1,50 +1,79 @@
|
||||
# [PROJECT_NAME] Constitution
|
||||
<!-- Example: Spec Constitution, TaskFlow Constitution, etc. -->
|
||||
# ss-tools Constitution
|
||||
|
||||
Конституция не дублирует правила — она объясняет, **почему** каждый принцип важен, и указывает, **где** искать полные инструкции.
|
||||
|
||||
## Core Principles
|
||||
|
||||
### [PRINCIPLE_1_NAME]
|
||||
<!-- Example: I. Library-First -->
|
||||
[PRINCIPLE_1_DESCRIPTION]
|
||||
<!-- Example: Every feature starts as a standalone library; Libraries must be self-contained, independently testable, documented; Clear purpose required - no organizational-only libraries -->
|
||||
### I. Semantic Contract First
|
||||
|
||||
### [PRINCIPLE_2_NAME]
|
||||
<!-- Example: II. CLI Interface -->
|
||||
[PRINCIPLE_2_DESCRIPTION]
|
||||
<!-- Example: Every library exposes functionality via CLI; Text in/out protocol: stdin/args → stdout, errors → stderr; Support JSON + human-readable formats -->
|
||||
Каждая единица кода (функция, класс, модуль, компонент) должна быть аннотирована GRACE-Poly контрактом. Без контракта код невидим для семантического индекса, непроверяем агентом и недоступен для impact analysis.
|
||||
|
||||
### [PRINCIPLE_3_NAME]
|
||||
<!-- Example: III. Test-First (NON-NEGOTIABLE) -->
|
||||
[PRINCIPLE_3_DESCRIPTION]
|
||||
<!-- Example: TDD mandatory: Tests written → User approved → Tests fail → Then implement; Red-Green-Refactor cycle strictly enforced -->
|
||||
**Немедленные правила** → [ADR-0002](docs/adr/ADR-0002-semantic-protocol.md)
|
||||
**Синтаксис и уровни сложности** → `skill({name="semantics-core"})`
|
||||
**Методология контрактов** → `skill({name="semantics-contracts"})`
|
||||
|
||||
### [PRINCIPLE_4_NAME]
|
||||
<!-- Example: IV. Integration Testing -->
|
||||
[PRINCIPLE_4_DESCRIPTION]
|
||||
<!-- Example: Focus areas requiring integration tests: New library contract tests, Contract changes, Inter-service communication, Shared schemas -->
|
||||
### II. Decision Memory
|
||||
|
||||
### [PRINCIPLE_5_NAME]
|
||||
<!-- Example: V. Observability, VI. Versioning & Breaking Changes, VII. Simplicity -->
|
||||
[PRINCIPLE_5_DESCRIPTION]
|
||||
<!-- Example: Text I/O ensures debuggability; Structured logging required; Or: MAJOR.MINOR.BUILD format; Or: Start simple, YAGNI principles -->
|
||||
Каждый архитектурный выбор, отвергающий альтернативу, должен быть записан: `@RATIONALE` (почему выбран этот путь) и `@REJECTED` (что запрещено и почему). Без этого агенты переоткрывают уже исследованные тупики, а долгоживущие сессии накапливают невидимый архитектурный дрейф.
|
||||
|
||||
## [SECTION_2_NAME]
|
||||
<!-- Example: Additional Constraints, Security Requirements, Performance Standards, etc. -->
|
||||
**Протокол ADR** → `skill({name="semantics-contracts"})` §I
|
||||
**Каталог решений** → [`docs/adr/`](docs/adr/)
|
||||
**Правило запрета воскрешения**: silently reintroducing `@REJECTED` pattern = fatal regression. Требуется `<ESCALATION>`.
|
||||
|
||||
[SECTION_2_CONTENT]
|
||||
<!-- Example: Technology stack requirements, compliance standards, deployment policies, etc. -->
|
||||
### III. External Orchestrator
|
||||
|
||||
## [SECTION_3_NAME]
|
||||
<!-- Example: Development Workflow, Review Process, Quality Gates, etc. -->
|
||||
ss-tools — внешний оркестратор над Apache Superset, а не плагин внутри него. Это даёт: независимый релизный цикл, отсутствие связанности с миграциями Superset, изоляцию DevOps-привилегий от BI-привилегий.
|
||||
|
||||
[SECTION_3_CONTENT]
|
||||
<!-- Example: Code review requirements, testing gates, deployment approval process, etc. -->
|
||||
**Полное обоснование** → [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
|
||||
<!-- Example: Constitution supersedes all other practices; Amendments require documentation, approval, migration plan -->
|
||||
|
||||
[GOVERNANCE_RULES]
|
||||
<!-- Example: All PRs/reviews must verify compliance; Complexity must be justified; Use [GUIDANCE_FILE] for runtime development guidance -->
|
||||
Конституция имеет приоритет над всеми остальными практиками разработки. Изменения требуют: документирования предложения, проверки на согласованность со всеми ADR, плана миграции затронутого кода, и bump версии.
|
||||
|
||||
**Version**: [CONSTITUTION_VERSION] | **Ratified**: [RATIFICATION_DATE] | **Last Amended**: [LAST_AMENDED_DATE]
|
||||
<!-- Example: Version: 2.1.1 | Ratified: 2025-06-13 | Last Amended: 2025-07-16 -->
|
||||
**Version**: 1.0.0 | **Ratified**: 2026-05-22 | **Last Amended**: 2026-05-22
|
||||
|
||||
Reference in New Issue
Block a user