94 lines
4.8 KiB
Markdown
94 lines
4.8 KiB
Markdown
# ss-tools Constitution
|
||
|
||
The constitution does not duplicate rules — it explains **why** each principle matters and **where** to find full instructions.
|
||
|
||
## Core Principles
|
||
|
||
### I. Semantic Contract First
|
||
|
||
Every code unit (function, class, module, component) MUST carry a GRACE-Poly contract. Without a contract, code is invisible to the semantic index, unverifiable by agents, and unreachable by impact analysis.
|
||
|
||
**Immediate rules** → [ADR-0002](docs/adr/ADR-0002-semantic-protocol.md)
|
||
**Syntax & complexity tiers** → `skill({name="semantics-core"})`
|
||
**Contract methodology** → `skill({name="semantics-contracts"})`
|
||
|
||
### II. Decision Memory
|
||
|
||
Every architectural choice that rejects an alternative MUST be recorded: `@RATIONALE` (why this path was chosen) and `@REJECTED` (what is forbidden and why). Without this, agents rediscover already-explored dead ends, and long-horizon sessions accumulate invisible architectural drift.
|
||
|
||
**ADR protocol** → `skill({name="semantics-contracts"})` §I
|
||
**Decision catalog** → [`docs/adr/`](docs/adr/)
|
||
**Resurrection ban**: silently reintroducing a `@REJECTED` pattern = fatal regression. Requires `<ESCALATION>`.
|
||
|
||
### III. External Orchestrator
|
||
|
||
ss-tools is an external orchestrator over Apache Superset, not a plugin inside it. This gives: independent release cycle, no coupling to Superset migrations, isolation of DevOps privileges from BI privileges.
|
||
|
||
**Full rationale** → [ADR-0003](docs/adr/ADR-0003-orchestrator-pattern.md)
|
||
|
||
### IV. Module Discipline
|
||
|
||
File >400 lines or function cyclomatic complexity >10 = signal to decompose. Canonical directory structure prevents circular imports and agent confusion in long speckit sessions.
|
||
|
||
**Structure & boundaries** → [ADR-0001](docs/adr/ADR-0001-module-layout.md)
|
||
|
||
### V. RBAC Enforcement
|
||
|
||
All mutating operations require explicit role check. DevOps privileges (deploy, migration, maintenance) are separated from BI privileges (dashboard viewing). Default-allow is forbidden.
|
||
|
||
**Role model & patterns** → [ADR-0005](docs/adr/ADR-0005-auth-rbac.md)
|
||
|
||
### VI. Frontend — Svelte 5 Runes Only
|
||
|
||
Only runes syntax (`$state`, `$derived`, `$effect`, `$props`). Legacy Svelte 4 syntax creates confusion and reactivity bugs. `fromStore` + multiple `$derived` causes infinite reactive flush loop — documented rejection.
|
||
|
||
**Frontend architecture** → [ADR-0006](docs/adr/ADR-0006-frontend-architecture.md)
|
||
**fromStore+$derived rejection** → [ADR-0007](docs/adr/ADR-0007-rejected-fromStore-derived.md)
|
||
**Component patterns** → `skill({name="semantics-svelte"})`
|
||
|
||
### VII. Test-Driven for C3+ Contracts
|
||
|
||
C3+ contracts require tests written before implementation. Tests verify `@PRE`/`@POST`/`@INVARIANT`, not implementation details. Minimum one test must explicitly verify that the `@REJECTED` path produces the expected failure.
|
||
|
||
**Testing methodology** → `skill({name="semantics-testing"})`
|
||
|
||
### VIII. Attention-Optimized Contracts
|
||
|
||
All generated contracts (specs, code, tests) MUST be optimized for the attention compression pipeline (MLA 3.5× → CSA 4×+top‑k → HCA 128× → DSA Lightning Indexer). Contracts that violate these rules become invisible to the model after context compression — causing downstream hallucination.
|
||
|
||
**Attention architecture & rules** → `skill({name="semantics-core"})` §VIII
|
||
|
||
**The four rules:**
|
||
- **ATTN_1**: First anchor line packs ID, complexity, type, and `@SEMANTICS` on ONE line (CSA 4× survival).
|
||
- **ATTN_2**: Hierarchical IDs: `Domain.Sub.Name` (HCA 128× survival).
|
||
- **ATTN_3**: Same-domain contracts share primary `@SEMANTICS` keyword (DSA Indexer grouping).
|
||
- **ATTN_4**: Contract ≤150 lines, module ≤400 lines (sliding window visibility).
|
||
|
||
## Development Workflow
|
||
|
||
```text
|
||
/speckit.specify → /speckit.clarify → /speckit.ux → /speckit.plan → /speckit.tasks → /speckit.implement
|
||
```
|
||
|
||
**Rules:**
|
||
- No phase is skipped when `[NEEDS CLARIFICATION]` markers remain
|
||
- `/speckit.ux` produces UX contracts AND generates Screen Model `.svelte.ts` files — these are the design contract for `/speckit.plan`
|
||
- Contract mutation: preview → apply, never immediate apply
|
||
- All feature artifacts in `specs/<feature>/`, never in `.kilo/` or `.ai/`
|
||
|
||
## Verification Gates
|
||
|
||
| Gate | Command |
|
||
|------|---------|
|
||
| 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
|
||
|
||
The constitution takes precedence over all other development practices. Amendments require: documented proposal, consistency check against all ADRs, migration plan for affected code, and version bump.
|
||
|
||
**Version**: 1.1.0 | **Ratified**: 2026-05-22 | **Last Amended**: 2026-06-05
|