diff --git a/.specify/memory/constitution.md b/.specify/memory/constitution.md index 0db4e32..c96b5f1 100644 --- a/.specify/memory/constitution.md +++ b/.specify/memory/constitution.md @@ -1,13 +1,13 @@ # 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 diff --git a/.specify/templates/tasks-template.md b/.specify/templates/tasks-template.md index 60f9be4..9177d9b 100644 --- a/.specify/templates/tasks-template.md +++ b/.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 -- [ ] T013 [P] [US1] Create [Entity2] model in src/models/[entity2].py -- [ ] T014 [US1] Implement [Service] in src/services/[service].py (depends on T012, T013) -- [ ] T015 [US1] Implement [endpoint/feature] in src/[location]/[file].py -- [ ] T016 [US1] Add validation and error handling -- [ ] T017 [US1] Add logging for user story 1 operations +> **Protocol Note**: Follow Semantic Protocol. Define contracts (`[DEF]`, `@PRE`, `@POST`) BEFORE implementing logic. + +- [ ] T012 [P] [US1] Define contracts/scaffolding for [Entity1] in src/models/[entity1].py +- [ ] T013 [P] [US1] Define contracts/scaffolding for [Entity2] in src/models/[entity2].py +- [ ] T014 [P] [US1] Implement logic for [Entity1] in src/models/[entity1].py +- [ ] 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 [US2] Implement [Service] in src/services/[service].py -- [ ] T022 [US2] Implement [endpoint/feature] in src/[location]/[file].py -- [ ] T023 [US2] Integrate with User Story 1 components (if needed) +- [ ] T021 [P] [US2] Define contracts/scaffolding for [Entity] in src/models/[entity].py +- [ ] T022 [P] [US2] Implement logic for [Entity] in src/models/[entity].py +- [ ] T023 [US2] Define contracts/scaffolding for [Service] in src/services/[service].py +- [ ] 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 -- [ ] T027 [US3] Implement [Service] in src/services/[service].py -- [ ] T028 [US3] Implement [endpoint/feature] in src/[location]/[file].py +- [ ] T028 [P] [US3] Define contracts/scaffolding for [Entity] in src/models/[entity].py +- [ ] T029 [P] [US3] Implement logic for [Entity] in src/models/[entity].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: -Task: "Create [Entity1] model in src/models/[entity1].py" -Task: "Create [Entity2] model in src/models/[entity2].py" +# Launch all contracts for User Story 1 together: +Task: "Define contracts/scaffolding for [Entity1] in src/models/[entity1].py" +Task: "Define contracts/scaffolding for [Entity2] in src/models/[entity2].py" ``` --- diff --git a/semantic_protocol.md b/semantic_protocol.md index 9d377f2..6ce7826 100755 --- a/semantic_protocol.md +++ b/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. ---