semantic add

.specify/memory/constitution.md

@@ -1,13 +1,13 @@
 <!--
 SYNC IMPACT REPORT
-Version: 1.2.0 (Configurable Belief Logs)
+Version: 1.5.0 (Fractal Complexity Limit)
 Changes:
-- Refined Belief State Logging principle to mandate Context Manager usage.
+- Added Section VI (Fractal Complexity Limit) to enforce strict module (~300 lines) and function (~30-50 lines) size limits.
-- Aligned logging states with Semantic Protocol.
+- Aims to maintain semantic coherence and avoid "Attention Sink".
 Templates Status:
-- .specify/templates/plan-template.md: ⚠ Pending (Needs update to include Component headers in checks).
+- .specify/templates/plan-template.md: ✅ Aligned.
 - .specify/templates/spec-template.md: ✅ Aligned.
-- .specify/templates/tasks-template.md: ⚠ Pending (Needs update to include Component definition tasks).
+- .specify/templates/tasks-template.md: ✅ Aligned.
 -->
 # Semantic Code Generation Constitution
 
@@ -20,7 +20,18 @@ Semantic definitions (Contracts) must ALWAYS precede implementation code. Logic
 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.
+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:module_name:Module]` must close with `[/DEF:module_name:Module]`).**
+
+**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.
@@ -28,6 +39,13 @@ Contracts are the Source of Truth. Functions and Classes must define their purpo
 ### 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
@@ -62,6 +80,6 @@ This Constitution establishes the "Semantic Code Generation Protocol" as the sup
 - **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.
+- **Compliance**: Failure to adhere to the `[DEF]` / `[/DEF]` structure (including matching closing tags) constitutes a build failure.
 
-**Version**: 1.2.0 | **Ratified**: 2025-12-19 | **Last Amended**: 2025-12-27
+**Version**: 1.5.0 | **Ratified**: 2025-12-19 | **Last Amended**: 2025-12-27

.specify/templates/tasks-template.md

@@ -88,12 +88,17 @@ Examples of foundational tasks (adjust based on your project):
 
 ### Implementation for User Story 1
 
-- [ ] T012 [P] [US1] Create [Entity1] model in src/models/[entity1].py
+> **Protocol Note**: Follow Semantic Protocol. Define contracts (`[DEF]`, `@PRE`, `@POST`) BEFORE implementing logic.
-- [ ] T013 [P] [US1] Create [Entity2] model in src/models/[entity2].py
+
-- [ ] T014 [US1] Implement [Service] in src/services/[service].py (depends on T012, T013)
+- [ ] T012 [P] [US1] Define contracts/scaffolding for [Entity1] in src/models/[entity1].py
-- [ ] T015 [US1] Implement [endpoint/feature] in src/[location]/[file].py
+- [ ] T013 [P] [US1] Define contracts/scaffolding for [Entity2] in src/models/[entity2].py
-- [ ] T016 [US1] Add validation and error handling
+- [ ] T014 [P] [US1] Implement logic for [Entity1] in src/models/[entity1].py
-- [ ] T017 [US1] Add logging for user story 1 operations
+- [ ] T015 [P] [US1] Implement logic for [Entity2] in src/models/[entity2].py
+- [ ] T016 [US1] Define contracts/scaffolding for [Service] in src/services/[service].py
+- [ ] T017 [US1] Implement logic for [Service] in src/services/[service].py
+- [ ] T018 [US1] Define contracts/scaffolding for [endpoint/feature] in src/[location]/[file].py
+- [ ] T019 [US1] Implement logic for [endpoint/feature] in src/[location]/[file].py
+- [ ] T020 [US1] Verify semantic compliance and belief state logging
 
 **Checkpoint**: At this point, User Story 1 should be fully functional and testable independently
 
@@ -112,10 +117,13 @@ Examples of foundational tasks (adjust based on your project):
 
 ### Implementation for User Story 2
 
-- [ ] T020 [P] [US2] Create [Entity] model in src/models/[entity].py
+- [ ] T021 [P] [US2] Define contracts/scaffolding for [Entity] in src/models/[entity].py
-- [ ] T021 [US2] Implement [Service] in src/services/[service].py
+- [ ] T022 [P] [US2] Implement logic for [Entity] in src/models/[entity].py
-- [ ] T022 [US2] Implement [endpoint/feature] in src/[location]/[file].py
+- [ ] T023 [US2] Define contracts/scaffolding for [Service] in src/services/[service].py
-- [ ] T023 [US2] Integrate with User Story 1 components (if needed)
+- [ ] T024 [US2] Implement logic for [Service] in src/services/[service].py
+- [ ] T025 [US2] Define contracts/scaffolding for [endpoint/feature] in src/[location]/[file].py
+- [ ] T026 [US2] Implement logic for [endpoint/feature] in src/[location]/[file].py
+- [ ] T027 [US2] Integrate with User Story 1 components (if needed)
 
 **Checkpoint**: At this point, User Stories 1 AND 2 should both work independently
 
@@ -134,9 +142,12 @@ Examples of foundational tasks (adjust based on your project):
 
 ### Implementation for User Story 3
 
-- [ ] T026 [P] [US3] Create [Entity] model in src/models/[entity].py
+- [ ] T028 [P] [US3] Define contracts/scaffolding for [Entity] in src/models/[entity].py
-- [ ] T027 [US3] Implement [Service] in src/services/[service].py
+- [ ] T029 [P] [US3] Implement logic for [Entity] in src/models/[entity].py
-- [ ] T028 [US3] Implement [endpoint/feature] in src/[location]/[file].py
+- [ ] T030 [US3] Define contracts/scaffolding for [Service] in src/services/[service].py
+- [ ] T031 [US3] Implement logic for [Service] in src/services/[service].py
+- [ ] T032 [US3] Define contracts/scaffolding for [endpoint/feature] in src/[location]/[file].py
+- [ ] T033 [US3] Implement logic for [endpoint/feature] in src/[location]/[file].py
 
 **Checkpoint**: All user stories should now be independently functional
 
@@ -179,6 +190,7 @@ Examples of foundational tasks (adjust based on your project):
 ### Within Each User Story
 
 - Tests (if included) MUST be written and FAIL before implementation
+- **Contracts First**: Define module structure and contracts (`[DEF]`, `@PRE`, `@POST`) before logic
 - Models before services
 - Services before endpoints
 - Core implementation before integration
@@ -202,9 +214,9 @@ Examples of foundational tasks (adjust based on your project):
 Task: "Contract test for [endpoint] in tests/contract/test_[name].py"
 Task: "Integration test for [user journey] in tests/integration/test_[name].py"
 
-# Launch all models for User Story 1 together:
+# Launch all contracts for User Story 1 together:
-Task: "Create [Entity1] model in src/models/[entity1].py"
+Task: "Define contracts/scaffolding for [Entity1] in src/models/[entity1].py"
-Task: "Create [Entity2] model in src/models/[entity2].py"
+Task: "Define contracts/scaffolding for [Entity2] in src/models/[entity2].py"
 ```
 
 ---

semantic_protocol.md

@@ -13,6 +13,7 @@ This protocol standardizes the "Semantic Bridge" between the two languages using
 2.  **Immutability:** Architectural decisions defined in the Module/Component Header are treated as immutable constraints.
 3.  **Format Compliance:** Output must strictly follow the `[DEF]` / `[/DEF]` anchor syntax for structure.
 4.  **Logic over Assertion:** Contracts define the *logic flow*. Do not generate explicit `assert` statements unless requested. The code logic itself must inherently satisfy the Pre/Post conditions (e.g., via control flow, guards, or types).
+5.  **Fractal Complexity:** Modules and functions must adhere to strict size limits (~300 lines/module, ~30-50 lines/function) to maintain semantic focus.
 
 ---