docs: ratify constitution v1.0.0 (semantic code generation protocol)

.specify/memory/constitution.md

@@ -0,0 +1,57 @@
+<!--
+SYNC IMPACT REPORT
+Version: 1.0.0 (Initial Ratification)
+Changes:
+- Established Core Principles based on Semantic Code Generation Protocol.
+- Defined Causal Validity, Immutability, Format Compliance, DbC, and Belief State Logging.
+- Added Section: File Structure Standards.
+- Added Section: Generation Workflow.
+Templates Status:
+- .specify/templates/plan-template.md: ✅ Aligned (Constitution Check section refers to constitution).
+- .specify/templates/spec-template.md: ✅ Aligned (Requirements section allows for functional constraints).
+- .specify/templates/tasks-template.md: ✅ Aligned (Supports contract/test-first workflow).
+-->
+# 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:
+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.0.0 | **Ratified**: 2025-12-19 | **Last Amended**: 2025-12-19