ss-tools/.specify/memory/constitution.md

Semantic Code Generation Constitution

Core Principles

I. Causal Validity (Contracts First)

Semantic definitions (Contracts) must ALWAYS precede implementation code. Logic is downstream of definition. We define the structure and constraints ([DEF], @PRE, @POST) before writing the executable logic. This ensures that the "what" and "why" govern the "how".

II. Immutability of Architecture

Once defined, architectural decisions in the Module Header (@LAYER, @INVARIANT, @CONSTRAINT) are treated as immutable constraints for that module. Changes to these require an explicit refactoring step, not ad-hoc modification during implementation.

III. Semantic Format Compliance

All output must strictly follow the [DEF] / [/DEF] anchor syntax with specific Metadata Tags (@KEY) and Graph Relations (@RELATION). Crucially, the closing anchor must strictly match the full content of the opening anchor (e.g., [DEF:identifier:Type] must close with [/DEF:identifier:Type]).

Standardized Graph Relations To ensure the integrity of the Semantic Graph, @RELATION must use a strict taxonomy:

• DEPENDS_ON (Structural dependency)
• CALLS (Flow control)
• CREATES (Instantiation)
• INHERITS_FROM / IMPLEMENTS (OOP hierarchy)
• READS_STATE / WRITES_STATE (Data flow)
• DISPATCHES / HANDLES (Event flow)

Ad-hoc relationships are forbidden. This structure is non-negotiable as it ensures the codebase remains machine-readable, fractal-structured, and optimized for Sparse Attention navigation by AI agents.

IV. Design by Contract (DbC)

Contracts are the Source of Truth. Functions and Classes must define their purpose, specifications, and constraints (@PRE, @POST, @THROW) in the metadata block before implementation. Implementation must strictly satisfy these contracts.

V. Belief State Logging

Logs must define the agent's internal state for debugging and coherence checks. We use a strict format: [{ANCHOR_ID}][{STATE}] {MESSAGE}. For Python, a Context Manager pattern MUST be used to automatically handle Entry, Exit, and Coherence states, ensuring structural integrity and error capturing.

VI. Fractal Complexity Limit

To maintain semantic coherence and avoid "Attention Sink" issues:

• Module Size: If a Module body exceeds ~300 lines (or logical complexity), it MUST be refactored into sub-modules or a package structure.
• Function Size: Functions should fit within a standard attention "chunk" (approx. 30-50 lines). If larger, logic MUST be decomposed into helper functions with their own contracts.

This ensures every vector embedding remains sharp and focused.

File Structure Standards

Python Modules

Every .py file must start with a Module definition header ([DEF:module_name:Module]) containing:

• @SEMANTICS: Keywords for vector search.
• @PURPOSE: Primary responsibility of the module.
• @LAYER: Architecture layer (Domain/Infra/UI).
• @RELATION: Dependencies.
• @INVARIANT & @CONSTRAINT: Immutable rules.
• @PUBLIC_API: Exported symbols.

Svelte Components

Every .svelte file must start with a Component definition header ([DEF:ComponentName:Component]) wrapped in an HTML comment <!-- ... --> containing:

• @SEMANTICS: Keywords for vector search.
• @PURPOSE: Primary responsibility of the component.
• @LAYER: Architecture layer (UI/State/Layout).
• @RELATION: Child components, Stores used, API calls.
• @PROPS: Input properties.
• @EVENTS: Emitted events.
• @INVARIANT: Immutable UI/State rules.

Generation Workflow

The development process follows a strict sequence enforced by Agent Roles:

1. Architecture Phase (Mode: tech-lead)

Input: tasks-arch.md Responsibility:

• Analyze request and graph position.
• Generate [DEF] anchors, Headers, and Contracts (@PRE, @POST).
• Output: Scaffolding files with no implementation logic.

2. Implementation Phase (Mode: code)

Input: tasks-dev.md + Scaffolding files Responsibility:

• Read contracts defined by Architect.
• Write implementation code that strictly satisfies contracts.
• Output: Working code with passing tests.

3. Validation

If logic conflicts with Contract -> Stop -> Report Error.

Governance

This Constitution establishes the "Semantic Code Generation Protocol" as the supreme law of this repository.

• Automated Enforcement: All code generation tools and agents must parse and validate adherence to the [DEF] syntax and Contract requirements.
• Amendments: Changes to the syntax or core principles require a formal amendment to this Constitution and a corresponding update to the constitution
• Review: Code reviews must verify that implementation matches the preceding contracts and that no "naked code" exists outside of semantic anchors.
• Compliance: Failure to adhere to the [DEF] / [/DEF] structure (including matching closing tags) constitutes a build failure.

Version: 1.5.0 | Ratified: 2025-12-19 | Last Amended: 2025-12-27