# 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