docs: Add comprehensive implementation plan and task list for feature 001

features/001-core-ast-structure/tasks.md

@@ -0,0 +1,847 @@
+# Implementation Tasks: Core AST Structure (Feature 001)
+
+**Feature**: Core AST Structure for SemAnno
+**Phase**: Planning Complete → Ready for Phase 1 Execution
+**Total Tasks**: 26
+**Estimated Duration**: 42-53 hours
+
+---
+
+## Legend
+
+- **[PHASE]**: 0 (Research), 1 (Structure), 2 (Editors), 3 (Testing)
+- **[PRIORITY]**: P0 (blocker), P1 (must-have), P2 (should-have), P3 (nice-to-have)
+- **[DURATION]**: Estimated hours
+- **[DEPENDS]**: Task IDs that must complete first
+
+---
+
+## Phase 0: Research & Exploration
+
+### RESEARCH-1: MPS Editor Design Patterns for Projections
+**Priority**: P1 | **Duration**: 2h | **Depends**: None
+**Status**: Pending
+
+**Objective**: Research how MPS languages support multiple projections (e.g., Python and C++ views on same AST).
+
+**Tasks**:
+- Read MPS Language Design documentation on projection cells
+- Find 2-3 examples in jetbrains.mps.lang.* languages (e.g., editor, structure)
+- Document patterns: how are editors structured to allow runtime projection switching?
+- Create summary: "Editor Design Patterns" with code examples
+
+**Definition of Done**:
+- Summary document created
+- At least 2 patterns identified and documented
+- Phase 1 editor design can proceed using these patterns
+
+---
+
+### RESEARCH-2: Nested Type Composition in MPS
+**Priority**: P1 | **Duration**: 2h | **Depends**: None
+**Status**: Pending
+
+**Objective**: Verify that deeply nested type references don't cause circular dependencies or serialization issues.
+
+**Tasks**:
+- Research MPS reference composition patterns
+- Test if Type → Type references can create lists[map[string, int]] without circular deps
+- Document: How to prevent cycles, how to serialize nested structures
+- Prepare example: 3-4 levels of nesting (list[map[string, optional[int]]])
+
+**Definition of Done**:
+- Patterns documented
+- Circular reference prevention strategy clear
+- Example type hierarchy designed
+
+---
+
+### RESEARCH-3: Annotation Attachment Patterns
+**Priority**: P1 | **Duration**: 2h | **Depends**: None
+**Status**: Pending
+
+**Objective**: Understand best practices for attaching multiple independent annotations to a single node.
+
+**Tasks**:
+- Research multi-valued references in MPS
+- Study how jetbrains.mps.lang.core.structure handles attributes/annotations
+- Verify: Can a Function have [DerefStrategy, OptimizationLock, LangSpecific] simultaneously?
+- Document ordering, optional/required logic, removal behavior
+
+**Definition of Done**:
+- Annotation design pattern documented
+- Multi-valued reference behavior verified
+- Phase 1 structure design can proceed
+
+---
+
+## Phase 1: Core Structure Definition
+
+### TASK-1-1: Define Root & Container Concepts
+**Priority**: P0 | **Duration**: 2h | **Depends**: None
+**Phase**: 1
+**Status**: Pending
+
+**Objective**: Define Module concept and establish container pattern.
+
+**Subtasks**:
+1. Create Module concept in SemAnno.structure.mps
+   - name: string property
+   - annotations: Annotation* reference (multi-valued)
+   - variables: Variable* reference (multi-valued)
+   - functions: Function* reference (multi-valued)
+2. Verify MPS recognizes all properties and references
+3. Mark concept as "root" in MPS (if applicable)
+
+**Definition of Done**:
+- Module concept defined and saved
+- MPS structure editor shows concept without errors
+- All 4 features (name property, 3 references) visible in model tree
+
+**Review Criteria**:
+- [ ] Concept name, property names match spec
+- [ ] References are multi-valued where appropriate
+- [ ] No red errors in MPS
+
+---
+
+### TASK-1-2: Define Function & Parameter Concepts
+**Priority**: P0 | **Duration**: 3h | **Depends**: TASK-1-1
+**Phase**: 1
+**Status**: Pending
+
+**Objective**: Define Function and Parameter concepts with proper signature structure.
+
+**Subtasks**:
+1. Create Function concept
+   - name: string property
+   - parameters: Parameter* reference (multi-valued, ordered)
+   - returnType: Type reference (single)
+   - body: Statement* reference (multi-valued, ordered)
+   - annotations: Annotation* reference (multi-valued)
+2. Create Parameter concept
+   - name: string property
+   - type: Type reference (single)
+   - defaultValue: Expression? reference (optional)
+3. Verify Function.parameters and Parameter.type are composable
+4. Test: Create Function, add 2 Parameters with types, set returnType
+
+**Definition of Done**:
+- Function and Parameter concepts defined
+- Parameter ordering preserved
+- Type references are composable (Type → Type reference works)
+- Can create function with 2 parameters in test model without errors
+
+---
+
+### TASK-1-3: Define Variable Concept
+**Priority**: P0 | **Duration**: 1h | **Depends**: TASK-1-1
+**Phase**: 1
+**Status**: Pending
+
+**Objective**: Define Variable concept for module and local variables.
+
+**Subtasks**:
+1. Create Variable concept
+   - name: string property
+   - type: Type reference (single)
+   - initializer: Expression? reference (optional)
+   - annotations: Annotation* reference (multi-valued)
+2. Ensure Variable can be added to Module.variables
+3. Test: Create Module → add Variable with type and initializer
+
+**Definition of Done**:
+- Variable concept defined
+- Can be added to Module and function scopes
+- No errors in test model
+
+---
+
+### TASK-1-4: Define All Statement Concepts
+**Priority**: P0 | **Duration**: 5h | **Depends**: TASK-1-2
+**Phase**: 1
+**Status**: Pending
+
+**Objective**: Define abstract Statement parent and 7 concrete statement types.
+
+**Subtasks**:
+1. Create abstract Statement concept (parent)
+2. Create concrete statement concepts:
+   - **Block**: statements: Statement* (multi-valued)
+   - **Assignment**: target: Expression, value: Expression
+   - **IfStatement**: condition: Expression, thenBranch: Statement*, elseBranch: Statement? (optional)
+   - **WhileLoop**: condition: Expression, body: Statement*
+   - **ForLoop**: iteratorName: string property, iterable: Expression, body: Statement*
+   - **Return**: value: Expression? (optional)
+   - **ExpressionStatement**: expression: Expression
+3. Verify inheritance hierarchy (all inherit from Statement)
+4. Test: Create function → add each statement type to body
+5. Test nesting: Block → Assignment → BinaryOperation expression
+6. Verify statement ordering is preserved
+
+**Definition of Done**:
+- All 7 concrete statement types defined
+- All inherit from Statement parent
+- Can create function with mixed statement types
+- Nesting works (statements inside blocks, expressions inside statements)
+- No errors in test model
+
+**Review Criteria**:
+- [ ] All statement types from spec are defined
+- [ ] Abstract Statement parent established
+- [ ] Multi-valued statement references are ordered
+- [ ] Optional references (elseBranch, return value) work correctly
+
+---
+
+### TASK-1-5: Define All Expression Concepts
+**Priority**: P0 | **Duration**: 5h | **Depends**: TASK-1-4
+**Phase**: 1
+**Status**: Pending
+
+**Objective**: Define abstract Expression parent and 13 concrete expression types.
+
+**Subtasks**:
+1. Create abstract Expression concept (parent)
+2. Create concrete expression concepts:
+   - **BinaryOperation**: operator: string, left: Expression, right: Expression
+   - **UnaryOperation**: operator: string, operand: Expression
+   - **FunctionCall**: functionName: string, arguments: Expression* (multi-valued)
+   - **VariableReference**: variableName: string
+   - **IntegerLiteral**: value: integer
+   - **FloatLiteral**: value: float
+   - **StringLiteral**: value: string
+   - **BooleanLiteral**: value: boolean
+   - **NullLiteral**: (no properties)
+   - **ListLiteral**: elements: Expression* (multi-valued)
+   - **IndexAccess**: target: Expression, index: Expression
+   - **MemberAccess**: target: Expression, memberName: string
+3. Verify inheritance hierarchy
+4. Test: Create Assignment with BinaryOperation on right side
+5. Test nesting: FunctionCall → BinaryOperation arguments
+6. Test all literal types can be created
+
+**Definition of Done**:
+- All 13 concrete expression types defined
+- All inherit from Expression parent
+- Can create complex nested expressions
+- Literals can be created and have correct value types
+- No errors in test model
+
+**Review Criteria**:
+- [ ] All expression types from spec defined
+- [ ] Abstract Expression parent established
+- [ ] Expression nesting works (expressions contain expressions)
+- [ ] Operator strings work as properties
+- [ ] Argument lists for FunctionCall are ordered
+
+---
+
+### TASK-1-6: Define All Type Concepts
+**Priority**: P0 | **Duration**: 4h | **Depends**: TASK-1-3
+**Phase**: 1
+**Status**: Pending
+
+**Objective**: Define abstract Type parent and 8 concrete type types with composition support.
+
+**Subtasks**:
+1. Create abstract Type concept (parent)
+2. Create concrete type concepts:
+   - **PrimitiveType**: kind: enum {int, float, string, bool}
+   - **ListType**: elementType: Type (reference)
+   - **SetType**: elementType: Type (reference)
+   - **MapType**: keyType: Type, valueType: Type
+   - **TupleType**: elementTypes: Type* (multi-valued, ordered)
+   - **ArrayType**: elementType: Type, size: Expression
+   - **OptionalType**: innerType: Type
+   - **CustomType**: typeName: string
+3. Verify Type → Type references are composable
+4. Test: Create type "list[map[string, int]]" by composition
+5. Test: Create type "optional[tuple[int, string, bool]]"
+6. Verify no circular reference issues
+7. Test: Create Variable with complex type, render in editor
+
+**Definition of Done**:
+- All 8 concrete type types defined
+- Type references are fully composable (ListType.elementType → MapType.keyType → PrimitiveType)
+- Can create complex nested types without errors
+- PrimitiveType enum values work correctly
+- No circular reference issues detected
+
+**Review Criteria**:
+- [ ] All type types from spec defined
+- [ ] Type composition works (type → type → type nesting)
+- [ ] Enum values for PrimitiveType are: int, float, string, bool
+- [ ] ArrayType.size accepts Expression references
+- [ ] TupleType elementTypes preserve order
+
+---
+
+### TASK-1-7: Define All Annotation Concepts
+**Priority**: P1 | **Duration**: 3h | **Depends**: TASK-1-2, TASK-1-5
+**Phase**: 1
+**Status**: Pending
+
+**Objective**: Define abstract Annotation parent and 3 concrete annotation types.
+
+**Subtasks**:
+1. Create abstract Annotation concept (parent, optional for extensibility)
+2. Create concrete annotation concepts:
+   - **DerefStrategy**:
+     - strategy: enum {imperative, streamed, batched, content_addressed}
+     - derefTime: Expression? (optional)
+     - derefLocation: string? (optional)
+     - owner: string? (optional)
+   - **OptimizationLock**:
+     - lockedBy: string
+     - lockReason: string
+     - lockLevel: enum {warning, soft, hard}
+     - affectedStrategies: string* (multi-valued)
+     - timestamp: string
+   - **LangSpecific**:
+     - language: enum {python, cpp, rust}
+     - idiomType: string
+     - rawSyntax: string
+     - semanticHint: string? (optional)
+     - position: enum {before, after, wrapping}
+3. Verify annotations can be attached to Function.annotations
+4. Test: Create Function with 1 DerefStrategy annotation
+5. Test: Create Variable with 1 LangSpecific annotation
+6. Test: Attach multiple annotations to same node
+
+**Definition of Done**:
+- All 3 concrete annotation types defined
+- Optional properties work (derefTime, owner, semanticHint)
+- Enum values are correct
+- Can attach annotations to functions and variables
+- Multi-valued affectedStrategies list works
+- No errors in test model
+
+---
+
+### TASK-1-8: Define Constraints & Validation Rules
+**Priority**: P1 | **Duration**: 2h | **Depends**: TASK-1-4, TASK-1-5, TASK-1-6
+**Phase**: 1
+**Status**: Pending
+
+**Objective**: Create SemAnno.constraints.mps with basic validation to prevent invalid structures.
+
+**Subtasks**:
+1. Create SemAnno.constraints.mps model file
+2. Define constraints:
+   - Statements can only appear in Statement* contexts (Block.statements, Function.body, etc.)
+   - Expressions can only appear in Expression contexts
+   - Types can only appear in Type contexts
+   - Statements cannot be direct children of Expression
+   - Expressions cannot be direct children of Statement (only in ExpressionStatement)
+3. Add can-be-parent/can-be-child rules to prevent invalid structures
+4. Test: Attempt to place a Statement inside an Expression context → should be blocked by constraint
+
+**Definition of Done**:
+- SemAnno.constraints.mps created
+- Basic structural constraints defined
+- MPS enforces constraint violations
+- Invalid structures are rejected during creation
+
+---
+
+### TASK-1-9: Create Test Model with Complex AST
+**Priority**: P0 | **Duration**: 3h | **Depends**: TASK-1-7
+**Phase**: 1
+**Status**: Pending
+
+**Objective**: Create SimpleExample.mps demonstrating all concept types.
+
+**Subtasks**:
+1. Create new SemAnno model file: `languages/SemAnno/tests/SimpleExample.mps`
+2. Create Module with name "example"
+3. Add 1 Function "sum" with:
+   - Parameters: items (list[int]), factor (float)
+   - returnType: float
+   - Body with 4 statements:
+     - ForLoop: iterate items, assign accumulator
+     - Assignment: result = accumulator * factor
+     - IfStatement: if factor > 0 then return result, else return 0
+     - Return: return result
+4. Add 1 Variable: cache (optional[map[string, list[int]]])
+5. Add annotations:
+   - DerefStrategy on function (strategy: batched)
+   - OptimizationLock on function (locked by "alice", reason "optimization")
+   - LangSpecific on variable (language: python, idiomType: "type_hint")
+6. Save and reload model in MPS
+7. Verify no errors, no warnings
+
+**Definition of Done**:
+- SimpleExample.mps created with all concept types demonstrated
+- Model includes: Module, Function, Parameters, Variable, all Statement types, nested Expressions, nested Types, Annotations
+- Model loads and renders without errors
+- Model serializes and deserializes correctly
+- No red errors in MPS error list
+
+**Acceptance Criteria**:
+- [ ] Module created with name
+- [ ] Function with 2 parameters, return type, body
+- [ ] Body contains ForLoop, Assignment, IfStatement, Return
+- [ ] Variable with complex nested type
+- [ ] All annotations attached and visible
+
+---
+
+## Phase 1 Completion Checkpoint
+
+**Validation Checklist**:
+- [ ] All 30+ concepts defined in SemAnno.structure.mps
+- [ ] SemAnno.constraints.mps created with validation rules
+- [ ] SimpleExample.mps created and loads without errors
+- [ ] MPS language rebuild: zero errors, zero warnings
+- [ ] All concept names match specification
+- [ ] All properties and references match specification
+
+**Approval**: Ready to proceed to Phase 2 (Editors) only if all checkpoints pass.
+
+---
+
+## Phase 2: Editor Definition
+
+### TASK-2-1: Define Module & Function Editors
+**Priority**: P0 | **Duration**: 3h | **Depends**: TASK-1-2
+**Phase**: 2
+**Status**: Pending
+
+**Objective**: Create editor definitions for Module, Function, Parameter concepts.
+
+**Subtasks**:
+1. Open SemAnno.editor.mps (create if needed)
+2. Define Module editor:
+   - Render: "module" (blue keyword), space, name (editable property), newline
+   - List functions and variables vertically, indented
+3. Define Function editor:
+   - Render: "def" (blue keyword), space, name, "(", parameters comma-separated, ")", space, "->", space, return type, ":", newline
+   - Body statements indented vertically
+4. Define Parameter editor:
+   - Render: name, ":", space, type reference
+5. Test in MPS:
+   - Create Module, add Function, add Parameters
+   - Verify rendering matches expected layout
+   - Verify indentation works
+
+**Definition of Done**:
+- Module, Function, Parameter editors defined
+- Editors render with proper syntax highlighting (blue keywords)
+- Indentation works for nested structures
+- Parameters display comma-separated
+- Return type reference is selectable
+
+---
+
+### TASK-2-2: Define All Statement Editors
+**Priority**: P0 | **Duration**: 5h | **Depends**: TASK-2-1
+**Phase**: 2
+**Status**: Pending
+
+**Objective**: Create editor definitions for all 7 statement types.
+
+**Subtasks**:
+1. Define Block editor:
+   - Render statements vertically, indented
+2. Define Assignment editor:
+   - Render: target, space, "=", space, value
+3. Define IfStatement editor:
+   - Render: "if" (blue), space, condition, ":", newline
+   - Then-branch indented
+   - Optional "else:" (blue), newline, else-branch indented
+4. Define WhileLoop editor:
+   - Render: "while" (blue), space, condition, ":", newline, body indented
+5. Define ForLoop editor:
+   - Render: "for" (blue), space, iteratorName, space, "in" (blue), space, iterable, ":", newline, body indented
+6. Define Return editor:
+   - Render: "return" (blue), space, optional value expression
+7. Define ExpressionStatement editor:
+   - Render: expression
+8. Test: Create function with mixed statements, verify layout
+
+**Definition of Done**:
+- All 7 statement editors defined
+- Syntax highlighting applied (keywords in blue)
+- Indentation rendered correctly for nested statements
+- Optional branches (else, return value) display when present, hidden when absent
+
+---
+
+### TASK-2-3: Define All Expression Editors
+**Priority**: P0 | **Duration**: 4h | **Depends**: TASK-2-2
+**Phase**: 2
+**Status**: Pending
+
+**Objective**: Create editor definitions for all 13 expression types.
+
+**Subtasks**:
+1. Define BinaryOperation editor:
+   - Render: left, space, operator, space, right
+2. Define UnaryOperation editor:
+   - Render: operator, operand
+3. Define FunctionCall editor:
+   - Render: functionName, "(", arguments comma-separated, ")"
+4. Define VariableReference editor:
+   - Render: variableName
+5. Define Literal editors (5 types):
+   - IntegerLiteral: value (number color - magenta)
+   - FloatLiteral: value (number color - magenta)
+   - StringLiteral: '"', value (string color - green), '"'
+   - BooleanLiteral: value (keyword color - blue)
+   - NullLiteral: "None" or "null" (keyword color - blue)
+6. Define ListLiteral editor:
+   - Render: "[", elements comma-separated, "]"
+7. Define IndexAccess editor:
+   - Render: target, "[", index, "]"
+8. Define MemberAccess editor:
+   - Render: target, ".", memberName
+9. Test: Create complex nested expressions, verify rendering
+
+**Definition of Done**:
+- All 13 expression editors defined
+- Syntax coloring applied (keywords blue, strings green, numbers magenta)
+- Operators and operands display correctly
+- Nested expressions render with proper precedence indication
+- Literals render with appropriate colors
+
+---
+
+### TASK-2-4: Define All Type Editors
+**Priority**: P0 | **Duration**: 3h | **Depends**: TASK-2-3
+**Phase**: 2
+**Status**: Pending
+
+**Objective**: Create editor definitions for all 8 type types.
+
+**Subtasks**:
+1. Define PrimitiveType editor:
+   - Render: kind enum value (int, float, string, bool)
+2. Define ListType editor:
+   - Render: "list" (blue), "[", elementType, "]"
+3. Define SetType editor:
+   - Render: "set" (blue), "[", elementType, "]"
+4. Define MapType editor:
+   - Render: "map" (blue), "[", keyType, ",", space, valueType, "]"
+5. Define TupleType editor:
+   - Render: "tuple" (blue), "[", elementTypes comma-separated, "]"
+6. Define ArrayType editor:
+   - Render: elementType, "[", size expression, "]"
+7. Define OptionalType editor:
+   - Render: innerType, "?"
+8. Define CustomType editor:
+   - Render: typeName
+9. Test: Create complex nested types (list[map[string, optional[int]]]), verify rendering
+
+**Definition of Done**:
+- All 8 type editors defined
+- Type keywords rendered in blue
+- Nested types render naturally (list[map[...]])
+- Type references are selectable
+- Composition works (can select complex types)
+
+---
+
+### TASK-2-5: Define Annotation Editors
+**Priority**: P1 | **Duration**: 2h | **Depends**: TASK-2-4
+**Phase**: 2
+**Status**: Pending
+
+**Objective**: Create editor definitions for all 3 annotation types.
+
+**Subtasks**:
+1. Define DerefStrategy editor:
+   - Render: "@deref" (gray), "(", strategy enum, optional properties as sub-lines, ")"
+2. Define OptimizationLock editor:
+   - Render: "@lock" (gray), "(", properties comma-separated, ")"
+   - Include: lockedBy, lockReason, lockLevel, affectedStrategies, timestamp
+3. Define LangSpecific editor:
+   - Render: "@lang_specific" (gray), "(", language, ",", idiomType, ",", rawSyntax, optional properties, ")"
+4. Test: Create function with each annotation type, verify rendering near function
+
+**Definition of Done**:
+- All 3 annotation editors defined
+- Annotation keywords in gray/italic (distinguishes from code)
+- Enum values display correctly
+- Optional properties hidden when absent
+- Annotations render attached to parent node
+
+---
+
+### TASK-2-6: Editor Testing & Refinement in MPS
+**Priority**: P0 | **Duration**: 3h | **Depends**: TASK-2-5
+**Phase**: 2
+**Status**: Pending
+
+**Objective**: Rebuild language in MPS, test editors interactively, fix issues.
+
+**Subtasks**:
+1. Rebuild SemAnno language in MPS
+   - Check for cell model errors
+   - Verify no "missing editor" errors
+2. Open SimpleExample.mps and manually verify:
+   - Module renders correctly (name, lists functions/variables)
+   - Function renders with "def", name, parameters, return type, body
+   - All statements render with proper indentation and syntax highlighting
+   - All expressions render correctly (operators, operands, nesting)
+   - All types render correctly (composition, nesting)
+   - Annotations render near their nodes
+3. Test interactive editing:
+   - Create new Module, add Function by adding statements
+   - Edit statement properties (if condition, loop iterator, etc.)
+   - Edit expression operators and operands
+   - Change types by selecting from dropdown
+   - Navigate between references (e.g., click parameter type → jump to Variable definition)
+4. Fix any rendering issues:
+   - Indentation not working → adjust cell layout
+   - Colors not applying → verify color codes
+   - References not selectable → verify reference cell type
+5. Document any workarounds or editor-specific behavior
+
+**Definition of Done**:
+- Language rebuilds with zero errors, zero warnings
+- All editors render without errors
+- Interactive editing works (properties editable, references selectable)
+- All syntax highlighting and indentation work correctly
+- SimpleExample.mps renders as designed
+
+**Acceptance Criteria**:
+- [ ] Language rebuild: zero errors
+- [ ] All concepts have working editors
+- [ ] Indentation works for nested structures
+- [ ] Syntax highlighting works (blue keywords, green strings, magenta numbers)
+- [ ] Properties can be edited inline
+- [ ] References are selectable
+
+---
+
+## Phase 2 Completion Checkpoint
+
+**Validation Checklist**:
+- [ ] All concept editors defined in SemAnno.editor.mps
+- [ ] MPS language rebuild: zero errors, zero warnings
+- [ ] SimpleExample.mps renders without editor errors
+- [ ] Manual AST creation works (can add statements, expressions, types)
+- [ ] Syntax highlighting and indentation correct
+- [ ] All references are selectable and navigable
+
+**Approval**: Ready to proceed to Phase 3 (Testing) only if all checkpoints pass.
+
+---
+
+## Phase 3: Integration & Testing
+
+### TASK-3-1: Create Extended Test Models
+**Priority**: P1 | **Duration**: 3h | **Depends**: TASK-2-6
+**Phase**: 3
+**Status**: Pending
+
+**Objective**: Create 3-5 test models demonstrating various AST structures.
+
+**Subtasks**:
+1. Create `SimpleFunction.mps`: Basic function (no loops, minimal types)
+   - Function: greet(name: string) -> string
+   - Body: Return StringLiteral
+2. Create `ComplexFunction.mps`: Nested control flow
+   - Function with ForLoop → IfStatement → BinaryOperation
+   - Demonstrates statement nesting
+3. Create `NestedTypes.mps`: Complex type structures
+   - Variables with types: list[map[string, optional[int]]], tuple[int, string, bool]
+   - Demonstrates type composition
+4. Create `WithAnnotations.mps`: Full example with annotations
+   - Function with DerefStrategy, OptimizationLock, LangSpecific
+   - Variables with annotations
+   - Demonstrates annotation attachment
+5. Save all models and verify load without errors
+
+**Definition of Done**:
+- 5 test models created
+- Each demonstrates different AST features
+- All load and render without errors
+- Each model documents its purpose in comments (if MPS supports)
+
+---
+
+### TASK-3-2: Test Model Serialization Round-Trips
+**Priority**: P0 | **Duration**: 2h | **Depends**: TASK-3-1
+**Phase**: 3
+**Status**: Pending
+
+**Objective**: Verify models persist correctly and don't corrupt on save/reload.
+
+**Subtasks**:
+1. For each test model:
+   - Save model to disk (automatic via MPS)
+   - Close MPS completely
+   - Reopen MPS and reload project
+   - Reload each test model
+   - Verify no errors, warnings, or corrupted nodes
+   - Verify content matches what was saved
+2. Test model properties:
+   - All string properties preserved correctly
+   - All enum values preserved
+   - All references intact (no broken links)
+   - Statement and type ordering preserved
+3. Document any serialization quirks or issues found
+
+**Definition of Done**:
+- All test models round-trip successfully (save → close → reopen → load)
+- No corruption or data loss detected
+- Content and structure verified after reload
+
+---
+
+### TASK-3-3: Quality & Correctness Verification
+**Priority**: P0 | **Duration**: 2h | **Depends**: TASK-3-2
+**Phase**: 3
+**Status**: Pending
+
+**Objective**: Run comprehensive checks to ensure language quality.
+
+**Subtasks**:
+1. Rebuild SemAnno language in MPS:
+   - Check for zero errors, zero warnings
+   - Verify all concept definitions are complete
+   - Verify all editor definitions are complete
+2. Run MPS consistency checks on all test models:
+   - Check for dangling references
+   - Check for orphaned nodes
+   - Verify hierarchy is valid
+3. Test constraint enforcement:
+   - Attempt to create invalid structure (e.g., Statement as Expression)
+   - Verify constraint blocks it
+4. Document findings: Are there any edge cases or limitations?
+
+**Definition of Done**:
+- Language rebuild: zero errors, zero warnings
+- All test models pass consistency checks
+- Constraints work as designed
+- No unresolved issues
+
+---
+
+### TASK-3-4: Write Quickstart Guide
+**Priority**: P1 | **Duration**: 2h | **Depends**: TASK-3-3
+**Phase**: 3
+**Status**: Pending
+
+**Objective**: Document how to create AST in SemAnno for future users.
+
+**Deliverable**: `languages/SemAnno/QUICKSTART.md`
+
+**Contents**:
+1. Overview: What is SemAnno, what can you do with it
+2. Step-by-step guide: Create first Module
+   - Create new model file
+   - Add Module concept
+   - Set module name
+3. Create first Function
+   - Add Function to Module.functions
+   - Set function name, return type
+   - Add parameters
+4. Create statements and expressions
+   - Add statements to function body
+   - Show examples: ForLoop, Assignment, Return
+   - Show expression examples: BinaryOperation, FunctionCall
+5. Work with types
+   - Create primitive type
+   - Create nested type (list[map[...]])
+   - Show how types compose
+6. Add annotations
+   - Attach DerefStrategy to function
+   - Attach OptimizationLock to variable
+7. Tips & tricks
+   - How to navigate references
+   - How to edit properties
+   - Keyboard shortcuts (if any)
+8. Examples section
+   - Link to test models (SimpleFunction.mps, ComplexFunction.mps, etc.)
+   - Show rendered output for each
+
+**Definition of Done**:
+- QUICKSTART.md created
+- All major workflows documented
+- Step-by-step instructions clear
+- Examples provided with screenshots or ASCII renderings
+- No unexplained concepts
+
+---
+
+### TASK-3-5: Prepare for Phase 2 Features (Python/C++ Projections)
+**Priority**: P2 | **Duration**: 1h | **Depends**: TASK-3-4
+**Phase**: 3
+**Status**: Pending
+
+**Objective**: Document how Phase 2 features will extend core AST.
+
+**Deliverable**: `languages/SemAnno/NEXT_PHASES.md`
+
+**Contents**:
+1. Overview: What comes next (Python Projection, C++ Projection, Tree-sitter Import)
+2. Python Projection (Week 3-4):
+   - Will extend editors to show Python-syntax rendering
+   - Will add Python text generator
+   - Will not change core AST structure
+   - Dependencies: This feature (core AST structure)
+3. C++ Projection (Week 5-6):
+   - Will extend editors to show C++-syntax rendering
+   - Will add C++ text generator
+   - Will add deref strategy translation
+   - Dependencies: This feature + Python Projection
+4. Tree-sitter Import (Week 7-8):
+   - Will add behavior model (SemAnno.behavior.mps) with import logic
+   - Will integrate tree-sitter-python and tree-sitter-cpp
+   - Will parse source files into AST
+   - Dependencies: This feature + both projections
+5. Warning System (Week 9-10):
+   - Will add OptimizationLock enforcement logic
+   - Will add warning UI to editors
+   - Will add provenance tracking
+   - Dependencies: All previous features
+6. Blockers or constraints for next phases (if any)
+
+**Definition of Done**:
+- NEXT_PHASES.md created
+- Clear roadmap for future features
+- Dependencies documented
+- No surprises in Phase 2+ implementation
+
+---
+
+## Phase 3 Completion Checkpoint
+
+**Validation Checklist**:
+- [ ] 5 test models created (SimpleFunction, ComplexFunction, NestedTypes, WithAnnotations, etc.)
+- [ ] All models load and render without errors
+- [ ] Serialization round-trips work (save → close → reopen)
+- [ ] Language rebuild: zero errors, zero warnings
+- [ ] Consistency checks pass
+- [ ] Constraints work as designed
+- [ ] Quickstart guide complete and clear
+- [ ] NEXT_PHASES.md prepared
+
+**Approval**: Feature 001 (Core AST Structure) is COMPLETE and ready for merge to parent branch.
+
+---
+
+## Summary
+
+**Total Tasks**: 26
+**Phases**: 3 (Research, Implementation, Testing)
+**Estimated Duration**: 42-53 hours
+**Status**: Ready for execution
+
+**Next Step**: Begin Phase 1 (TASK-1-1) with core structure definition.
+
+---
+
+## Approval Signature
+
+Once all tasks are complete and checkpoints pass:
+
+```
+Feature: 001 - Core AST Structure
+Status: ✅ COMPLETE
+Merged to: sprint-1-ast-redesign (parent branch)
+Timestamp: [Completion date]
+```