Feature/documentation workflow improvements

.github/prompts/workstream-execution.prompt.md

@@ -417,11 +417,11 @@ cargo test --test <name>  # Does THIS test pass?
 ```bash
 # All tests
 cargo test --workspace
-# Report: "✅ All 111 tests passing"
+# Report: "✅ All 222 tests passing"
 
-# Code quality
-cargo clippy --workspace --tests
-# Report: "✅ No clippy warnings on new files" or list warnings
+# Code quality (strict mode - treats warnings as errors)
+cargo clippy --workspace --all-targets --all-features -- -D warnings
+# Report: "✅ Clippy passed with zero warnings"
 
 # Formatting
 cargo fmt --all
@@ -707,8 +707,8 @@ Before marking work complete, ensure:
 ## ✅ Validation
 
 - [ ] All tests pass: `cargo test --workspace`
-- [ ] Code quality: `cargo clippy --workspace -- -D warnings`
-- [ ] Formatting: `cargo fmt -- --check`
+- [ ] Code quality: `cargo clippy --workspace --all-targets --all-features -- -D warnings`
+- [ ] Formatting: `cargo fmt --all` (then check with `cargo fmt --all -- --check`)
 - [ ] Documentation: `npm run docs:lint`
 - [ ] PR created and passing CI
 

CONTRIBUTING.md

@@ -229,7 +229,7 @@ Code contributions are welcome for:
 
 1. **Open an issue** (or comment on an existing one) to discuss your approach
 2. **Wait for feedback** from maintainers to ensure alignment
-3. **Create a feature branch** from `main` for your work
+3. **Create a feature branch** from `develop` for your work (e.g., `feature/my-feature`)
 
 #### Maintaining Syntax Highlighting
 
@@ -492,16 +492,18 @@ We have specialized templates for different PR types:
 
 Before your PR can be merged:
 
-- ✅ All tests must pass (`cargo test`)
-- ✅ Code must be formatted (`cargo fmt`)
-- ✅ Code must pass linting (`cargo clippy`)
+- ✅ All tests must pass (`cargo test --workspace`)
+- ✅ Code must be formatted (`cargo fmt --all`)
+- ✅ Code must pass strict linting (`cargo clippy --workspace --all-targets --all-features -- -D warnings`)
+- ✅ Documentation linting passes (`npm run docs:lint`)
 - ✅ Documentation must be updated (if applicable)
 - ✅ CHANGELOG.md must be updated (see below)
 - ✅ At least one maintainer approval
 
 ### Merge Strategy
 
-- **Feature branches**: We use **squash and merge** to keep main branch history clean
+- **Feature branches → develop**: We use **squash and merge** to keep develop branch history clean
+- **develop → main**: Merge commits for releases to preserve version history
 - **Hotfix branches**: We use **merge commit** to preserve context
 - **Branch deletion**: Branches are automatically deleted after merge (enable in your fork's settings)
 

docs/DEVELOPMENT.md

@@ -45,8 +45,8 @@ cargo test --workspace -- --show-output
 # Check code formatting
 cargo fmt --all -- --check
 
-# Run clippy linter
-cargo clippy --workspace -- -D warnings
+# Run clippy linter (strict - treats warnings as errors)
+cargo clippy --workspace --all-targets --all-features -- -D warnings
 
 # Generate documentation
 cargo doc --workspace --open
@@ -139,7 +139,7 @@ cargo test test_compile_hello
 
 # Check formatting and linting
 cargo fmt --all
-cargo clippy --workspace
+cargo clippy --workspace --all-targets --all-features -- -D warnings
 ```
 
 ### 4.5. Validate Documentation Changes
@@ -790,8 +790,9 @@ Before submitting a PR:
 
 - [ ] All tests pass (`cargo test --workspace`)
 - [ ] Code is formatted (`cargo fmt --all`)
-- [ ] No clippy warnings (`cargo clippy --workspace`)
+- [ ] No clippy warnings (strict mode: `cargo clippy --workspace --all-targets --all-features -- -D warnings`)
 - [ ] Documentation updated if needed
+- [ ] Documentation linting passes (`npm run docs:lint`)
 - [ ] Commit messages follow convention
 - [ ] PR description explains the change
 

docs/planning/v0.0.3/LEARNINGS.md

@@ -14,26 +14,65 @@ This document captures key insights, discoveries, and lessons learned during v0.
 
 ## 📊 Phase-Specific Learnings
 
-### Phase 1: Error Code System
+### Phase 1: Error Code System ✅
 
-**Date Started**: TBD  
-**Date Completed**: TBD
+**Date Started**: October 3, 2025  
+**Date Completed**: October 6, 2025  
+**PR**: [#27](https://github.com/dev-parkins/FerrisScript/pull/27)
 
 #### Technical Discoveries
 
-- *(To be filled during development)*
+- **Error Code Assignment Timing**: Error codes are assigned based on which compiler stage catches the error first, not necessarily the "most appropriate" category. For example, `let x: int = 5;` triggers type checking errors (E218/E200) rather than parser errors (E110) because the parser accepts it and type checker catches the invalid type.
+
+- **Error Code Organization**: 63 error codes implemented across 5 categories:
+  - Lexical (E001-E003): 3 codes for character, string, and escape sequence errors
+  - Syntax (E100-E113): 14 codes for parser-level errors
+  - Type (E200-E219): 19 codes for type checking errors
+  - Runtime (E400-E418): 24 codes for runtime errors
+  - Internal (E900-E999): Reserved for compiler bugs
+
+- **Validation Testing Strategy**: Test cases must match actual compiler behavior, not ideal behavior. Initial test cases needed adjustment because they triggered different error codes than expected.
+
+- **Documentation Scale**: Comprehensive error documentation (ERROR_CODES.md) reached 4,000+ lines with descriptions, examples, and fixes for each code.
 
 #### Challenges Encountered
 
-- *(To be filled during development)*
+- **Clippy Strict Mode**: Initial implementation passed regular `cargo clippy` but failed strict mode (`cargo clippy --workspace --all-targets --all-features -- -D warnings`). Found:
+  - `useless_vec` warnings in test code (should use arrays instead)
+  - Deprecated `criterion::black_box` usage (should use `std::hint::black_box`)
+
+- **Dependency Updates**: Updating from criterion 0.5 → 0.7 and godot 0.1 → 0.4 introduced breaking API changes:
+  - `criterion::black_box` deprecated in favor of `std::hint::black_box`
+  - godot 0.4 changed `GString` from pass-by-value to pass-by-reference in API calls
+
+- **Documentation Link Validation**: Found 11 broken markdown links across planning documents during final validation:
+  - Incorrect relative paths (missing `../` levels)
+  - Links to non-existent future phase documents
+  - Outdated roadmap filenames
 
 #### Solutions Applied
 
-- *(To be filled during development)*
+- **Test Adjustments**: Modified validation tests to match actual error code behavior rather than assumed behavior. Example: Used `let x: unknown_type = 5;` instead of `let x: int = 5;` to trigger specific parser errors.
+
+- **Strict Quality Gates**: Established `cargo clippy --workspace --all-targets --all-features -- -D warnings` as the standard for all future work to catch issues early and prevent tech debt accumulation.
+
+- **Dependency Migration**: Updated benchmark files to use `std::hint::black_box` and fixed godot API calls to pass `&GString` instead of cloning. All 222 tests still passing after updates.
+
+- **Documentation Hygiene**: Implemented systematic link checking with `npx markdown-link-check` and fixed all broken links before merging. Updated non-existent phase document links to show `*(To be created)*` placeholders.
 
 #### Best Practices Identified
 
-- *(To be filled during development)*
+- **Always Run Strict Clippy**: Use `cargo clippy --workspace --all-targets --all-features -- -D warnings` for final validation before any PR. This catches issues that standard clippy misses and prevents tech debt.
+
+- **Test Actual Behavior**: When writing validation tests, always verify the actual error codes produced by test cases rather than assuming which codes should appear.
+
+- **Document as You Go**: Comprehensive error documentation (with examples and fixes) should be created alongside implementation, not after. This ensures accuracy and completeness.
+
+- **Validate Links Before Commit**: Always run `npx markdown-link-check` on modified markdown files to catch broken links early. Follow DOCUMENTATION_LINKING_GUIDELINES.md for link best practices.
+
+- **Keep Dependencies Current**: Regularly update dependencies to latest stable versions to avoid accumulating breaking changes. Test thoroughly after updates.
+
+- **Format Code Before "Done"**: Always run `cargo fmt --all` before declaring work complete. Include this in all workflow documentation and checklists.
 
 ---
 
@@ -225,19 +264,171 @@ This document captures key insights, discoveries, and lessons learned during v0.
 
 ### Architecture Decisions
 
-- *(To be filled)*
+#### Error Code System Design
+
+- **Enum-Based Approach**: Using Rust enums for error codes provides type safety and compile-time validation. Each error code variant can have associated methods for description, category, and documentation URL.
+
+- **Category Organization**: Error codes organized by compiler stage (Lexical, Syntax, Type, Runtime, Internal) makes it easier to locate relevant errors and understand where in the compilation pipeline issues occur.
+
+- **Reserved Code Ranges**: Reserving gaps in error code ranges (E050-E099, E150-E199, etc.) allows for future expansion within categories without disrupting existing code organization.
 
 ### Performance Optimizations
 
-- *(To be filled)*
+- **Error Code Lookup**: Using match statements for error code descriptions is optimal for performance. Rust compiles these into efficient jump tables.
+
+- **Array vs Vec Performance**: Replacing `vec![]` with array literals `[]` in tests eliminates runtime heap allocation for better performance and clippy compliance.
 
 ### Testing Strategies
 
-- *(To be filled)*
+#### Validation Test Design
+
+- **Error Code Format Tests**: Validate that error codes follow the `Error[EXXX]:` format pattern consistently across all error types.
+
+- **Coverage Tests**: Ensure all error codes are documented and have descriptions. Test that error codes appear correctly in actual compiler output.
+
+- **Context Preservation**: Verify that error context (line numbers, code snippets) is preserved when error codes are added to messages.
 
 ### Tooling Improvements
 
-- *(To be filled)*
+#### Quality Gate Automation
+
+- **Strict Clippy Mode**: Established `cargo clippy --workspace --all-targets --all-features -- -D warnings` as standard. This catches issues in:
+  - Test code (not just main code)
+  - Benchmark code
+  - Example code
+  - All feature combinations
+
+- **Documentation Validation**: Integrated `npm run docs:lint` and `npx markdown-link-check` into workflow to catch documentation issues before CI.
+
+- **Format Consistency**: Always run `cargo fmt --all` before committing to maintain consistent code style across the entire workspace.
+
+---
+
+## 🔮 Deferred Investigations & Future Opportunities
+
+### Phase 1 Deferred Items
+
+#### Semantic Error Codes (E300-E399)
+
+**Status**: Deferred - No semantic analyzer yet
+
+**Opportunity**: When implementing semantic analysis in future versions, we have error code ranges reserved for:
+
+- E300: Unreachable code detection
+- E301-E303: Unused variable/function warnings
+- E304-E305: Invalid control flow (break/continue/return outside valid context)
+
+**Investigation Needed**: Research best practices for:
+
+- Dead code elimination strategies
+- Unused variable detection (accounting for intentional underscore prefixes)
+- Control flow validation in nested contexts
+
+#### Advanced Runtime Error Codes (E400-E404 deferred)
+
+**Status**: Error codes defined but not actively triggered by runtime
+
+**Opportunity**: Some runtime errors are defined but not yet detected:
+
+- E400: Division by zero (not checked at runtime yet)
+- E401: Index out of bounds (no array indexing implemented)
+- E402: Null pointer access (no null values in language)
+- E403: Stack overflow (no recursion depth limit)
+- E404: Memory exhaustion (relies on system limits)
+
+**Investigation Needed**:
+
+- Should runtime check for division by zero or rely on system signals?
+- When array indexing is added, what's the performance impact of bounds checking?
+- Is a recursion depth limit needed for FerrisScript's use case (game scripting)?
+
+### Opportunities Discovered During Phase 1
+
+#### Error Code Quick Fixes (LSP Integration)
+
+**Discovery**: Each error code has structured information (description, example, fix) that could power IDE quick fixes.
+
+**Opportunity**: When implementing LSP (Language Server Protocol) support:
+
+- Use error code descriptions for hover tooltips
+- Generate quick fixes from "How to Fix" sections
+- Link to ERROR_CODES.md documentation from IDE
+
+**Benefit**: Significantly improves developer experience with actionable error messages.
+
+#### Error Code Telemetry
+
+**Discovery**: Structured error codes enable tracking which errors users encounter most frequently.
+
+**Opportunity**: (Privacy-respecting) telemetry could identify:
+
+- Most common user errors (prioritize documentation/error messages)
+- Confusing error messages (improve wording)
+- Missing error codes (gaps in coverage)
+
+**Investigation Needed**:
+
+- Opt-in telemetry design
+- Privacy considerations
+- Storage and analysis approach
+
+#### Error Code Localization
+
+**Discovery**: Error code enum provides a centralization point for all error messages.
+
+**Opportunity**: Future internationalization (i18n) could:
+
+- Translate error descriptions while keeping error codes stable
+- Provide localized "How to Fix" guidance
+- Maintain English error codes for searchability
+
+**Investigation Needed**:
+
+- Which languages to support first?
+- How to maintain translation quality?
+- Performance impact of runtime locale selection?
+
+#### Machine-Readable Error Output
+
+**Discovery**: Error codes provide structured data that's currently only human-readable.
+
+**Opportunity**: Add JSON error output mode for:
+
+- IDE integration (structured diagnostics)
+- Build tool integration (error parsing)
+- CI/CD pipelines (automated failure analysis)
+
+**Example Format**:
+
+```json
+{
+  "errors": [
+    {
+      "code": "E201",
+      "message": "Undefined variable 'player'",
+      "file": "game.ferris",
+      "line": 10,
+      "column": 5,
+      "severity": "error"
+    }
+  ]
+}
+```
+
+**Investigation Needed**: Standardize on JSON schema for compatibility with existing tools.
+
+#### Error Code Documentation Website
+
+**Discovery**: ERROR_CODES.md is comprehensive but linear (must scroll to find codes).
+
+**Opportunity**: Generate a searchable website:
+
+- Search by error code or keyword
+- Browse by category
+- Show related errors
+- Link to GitHub issues/discussions for each code
+
+**Tools**: Could use mdBook, Docusaurus, or custom generator from ERROR_CODES.md.
 
 ---