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

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.

Generation Workflow

The development process follows a strict sequence:

Analyze Request: Identify target module and graph position.
Define Structure: Generate [DEF] anchors and Contracts FIRST.
Implement Logic: Write code satisfying Contracts.
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.0.0 | Ratified: 2025-12-19 | Last Amended: 2025-12-19

3.6 KiB Raw Blame History