# 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`). 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: `logger.level(f"[{ANCHOR_ID}][{STATE}] {MESSAGE} context={...}")` to track transitions between `Entry`, `Validation`, `Action`, and `Coherence` states. ## 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: 1. **Analyze Request**: Identify target module and graph position. 2. **Define Structure**: Generate `[DEF]` anchors and Contracts FIRST. 3. **Implement Logic**: Write code satisfying Contracts. 4. **Validate**: 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 constitutes a build failure. **Version**: 1.1.0 | **Ratified**: 2025-12-19 | **Last Amended**: 2025-12-19