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
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/
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

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

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

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
fromStore+$derived rejection → ADR-0007
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

/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

4.8 KiB Raw Blame History Unescape Escape