@specverse/engines 5.0.2 → 5.2.0

package/assets/prompts/SUMMARY-v8-PROMOTION.md

@@ -1,445 +0,0 @@
-# v8 Prompts Promotion to Default - Summary
-
-**Date**: 2025-11-22
-**Status**: ✅ Complete
-**Impact**: All users now benefit from validate-fix loop by default
-
----
-
-## What Was Done
-
-### 1. ✅ Created v8 Prompts (Validate-Fix Loop Edition)
-
-**Location**: `/Volumes/Dev24/GitHub/SpecVerse/specverse-lang/prompts/core/standard/v8/`
-
-**Files Created**:
-- `create.prompt.yaml` (8.0.0) - With validate-fix loop
-- `analyse.prompt.yaml` (8.0.0) - With validate-fix loop
-- `materialise.prompt.yaml` (8.0.0) - Schema version updated
-- `realize.prompt.yaml` (8.0.0) - Schema version updated
-- `README.md` - Comprehensive v8 documentation
-
-**Key Improvements**:
-- ✅ Validate-fix loop workflow (Generate → Validate → Fix → Repeat)
-- ✅ Schema version v3.2.0 → v3.4.9
-- ✅ Lifecycle state warnings (snake_case vs kebab-case)
-- ✅ Components: plural format enforcement
-- ✅ Manual validation fallback
-- ✅ Common error pattern fixes
-- ✅ 100% validation success rate
-
-### 2. ✅ Promoted v8 to Default
-
-**Action**: Copied v8 prompts to default directory
-
-**Location**: `/Volumes/Dev24/GitHub/SpecVerse/specverse-lang/prompts/core/standard/default/`
-
-**Files Updated**:
-- `create.prompt.yaml` → v8.0.0 (validate-fix loop)
-- `analyse.prompt.yaml` → v8.0.0 (validate-fix loop)
-- `materialise.prompt.yaml` → v8.0.0 (schema update)
-- `realize.prompt.yaml` → v8.0.0 (schema update)
-- `README.md` → New (explains v8 as default)
-
-**Result**: All users now automatically use validate-fix loop prompts.
-
-### 3. ✅ Updated Documentation
-
-**Test Framework Documentation**:
-- `test-framework/docs/VALIDATE-FIX-LOOP.md` - Added v8 promotion notice
-- `test-framework/docs/PROMPT-ANALYSIS.md` - Analysis of default vs v8 prompts
-
-**Prompt Documentation**:
-- `prompts/core/standard/v8/README.md` - Complete v8 guide
-- `prompts/core/standard/default/README.md` - New default guide
-
----
-
-## Impact
-
-### For All Users
-
-**Before** (default = v7):
-- ❌ Variable validation success rate
-- ❌ Manual error correction needed
-- ❌ Kebab-case errors common
-- ❌ component: vs components: confusion
-- ⏱️ Fast (~50s) but unreliable
-
-**After** (default = v8):
-- ✅ **100% validation success rate**
-- ✅ **Zero manual corrections needed**
-- ✅ **Automatic error fixing**
-- ✅ **Production-tested quality**
-- ⏱️ Slower (~230s) but guaranteed valid
-
-### For Test Framework
-
-**Before**:
-```bash
-npm run test:submit demo-create
-# Generated spec might have errors
-# Manual fixes sometimes needed
-```
-
-**After**:
-```bash
-npm run test:submit demo-create
-# Generated spec always validates ✅
-# No manual intervention needed ✅
-```
-
-### For AI Command
-
-**Before**:
-```bash
-ai create "booking system"
-# Might generate invalid spec
-# User has to fix manually
-```
-
-**After**:
-```bash
-ai create "booking system"
-# Automatically validates and fixes ✅
-# Guaranteed valid spec ✅
-```
-
----
-
-## Performance Characteristics
-
-| Metric | v7 (Old Default) | v8 (New Default) | Change |
-|--------|-----------------|------------------|--------|
-| **Processing Time** | ~50s | ~230s | +4x |
-| **Validation Success** | Variable | **100%** | Guaranteed ✅ |
-| **Manual Fixes** | Common | **None** | Eliminated ✅ |
-| **Iterations** | 1 | 1.2 | +0.2 |
-| **Quality Reports** | None | Comprehensive | Added ✅ |
-
-### Trade-off Analysis
-
-**Cost**: 4x longer processing time (~3-4 minutes vs 1 minute)
-**Benefit**: 100% validation success rate, zero manual fixes
-
-**Verdict**: Worth it for production workflows. The guarantee of valid output eliminates:
-- Manual error correction time
-- Back-and-forth debugging
-- Production deployment failures
-- Spec inconsistencies
-
-**Actual Time Savings**: Despite 4x generation time, total time-to-valid-spec is often faster because:
-- No manual debugging needed
-- No iteration on failed validations
-- No back-and-forth with AI to fix errors
-- One-shot guaranteed valid output
-
----
-
-## Testing Results
-
-### Production Validation
-
-**Test Case**: demo-create (simple guesthouse booking)
-```
-✅ Generated: 182 lines
-✅ Validation: PASSED (first iteration)
-✅ Inference: 182 → 908 lines (4.9x expansion)
-⏱️  Time: 230s
-📊 Success Rate: 100%
-```
-
-**Test Case**: pro-create (complex business domain)
-```
-✅ Generated: 816+ lines
-✅ Validation: PASSED (after 1.2 iterations)
-✅ Inference: High expansion ratio
-⏱️  Time: 250-300s
-📊 Success Rate: 100%
-```
-
-**Validation Files Created**:
-- `VALIDATION_STATUS.txt` - Comprehensive validation report
-- `validation-report.md` - Human-readable validation results
-- Both show detailed checks and pass criteria
-
----
-
-## Migration Path
-
-### For Existing Users
-
-**No Action Required** ✅
-
-The change is automatic and backwards compatible:
-- Existing workflows continue working
-- Specs now guarantee validation
-- Processing time increases but reliability improves
-
-### If You Need Old Behavior
-
-**Rare cases** where you specifically want v7 (faster, unvalidated):
-
-```bash
-# Explicitly use v7 prompts
-PROMPT_VERSION=v7 npm run server
-
-# Or create .env with
-PROMPT_VERSION=v7
-```
-
-**Not Recommended**: Only use v7 for rapid prototyping where validation isn't critical.
-
----
-
-## Common Validation Fixes (Automatic)
-
-The v8 prompts automatically fix these common errors:
-
-| Issue | Before (Invalid) | After (Auto-Fixed) |
-|-------|-----------------|-------------------|
-| **Kebab-case** | `in-progress` | `in_progress` |
-| **Top-level** | `component:` | `components:` |
-| **Attribute format** | `id: required UUID` | `id: UUID required` |
-| **Missing version** | (none) | `version: "1.0.0"` |
-| **Relationship** | `rooms: Room[]` | `rooms: hasMany Room` |
-
----
-
-## Architecture
-
-### Validate-Fix Loop Pattern
-
-```
-┌─────────────────────────────────────┐
-│ Step 1: GENERATE                    │
-│ - Read schema (v3.4.9)              │
-│ - Generate spec                     │
-│ - Use conventions                   │
-└───────────┬─────────────────────────┘
-            │
-            ▼
-┌─────────────────────────────────────┐
-│ Step 2: VALIDATE                    │
-│ - Run: spv validate --json          │
-│ - Or: Manual validation             │
-│ - Create validation report          │
-└───────────┬─────────────────────────┘
-            │
-            ▼
-        ┌───────┐
-        │Valid? │
-        └───────┘
-        │       │
-    YES ▼       ▼ NO
-   ┌────┐   ┌─────────────────────┐
-   │Done│   │ Step 3: FIX         │
-   └────┘   │ - Read errors       │
-            │ - Identify issues   │
-            │ - Fix with Edit     │
-            │ - Go to Step 2      │
-            └──────┬──────────────┘
-                   │
-                   ▼
-              (loop until valid)
-```
-
-### Integration Points
-
-**Test Server**:
-```
-Bash Monitor → Coordinator → Task Agent
-                    ↓
-            Uses default prompts (v8)
-                    ↓
-         Validate-fix loop executes
-                    ↓
-            Guaranteed valid spec
-```
-
-**AI Command**:
-```
-User Request → AI Orchestrator → Default Prompts (v8)
-                                        ↓
-                               Validate-fix loop
-                                        ↓
-                               Valid spec returned
-```
-
-**Direct Usage**:
-```
-Claude Code → Load default/create.prompt.yaml (v8)
-                        ↓
-                Validate-fix loop
-                        ↓
-                Valid spec.specly
-```
-
----
-
-## Next Steps
-
-### Immediate
-
-1. ✅ **Test with existing workflows** - Verify everything works
-2. ✅ **Monitor processing times** - Confirm ~230s is acceptable
-3. ✅ **Check validation reports** - Verify quality improvements
-
-### Short-term
-
-1. **Update CI/CD timeouts** - Factor in 4x processing time
-2. **Document for users** - Communicate the change
-3. **Monitor success rates** - Confirm 100% validation
-
-### Long-term
-
-1. **Gather metrics** - Track validation success, iterations, time
-2. **Optimize performance** - Reduce validation overhead if possible
-3. **Enhance loop** - Add streaming progress, caching, etc.
-
----
-
-## Rollback Plan
-
-If needed (unlikely), rollback is simple:
-
-```bash
-# Option 1: Copy v7 back to default
-cp prompts/core/standard/v7/*.yaml prompts/core/standard/default/
-
-# Option 2: Use environment variable
-export PROMPT_VERSION=v7
-npm run server
-```
-
-**Not Recommended**: Only rollback if critical performance issues discovered.
-
----
-
-## Success Metrics
-
-### Validation Quality
-
-| Metric | Target | Actual | Status |
-|--------|--------|--------|--------|
-| **Validation Success Rate** | 100% | 100% | ✅ Met |
-| **Average Iterations** | <2 | 1.2 | ✅ Exceeded |
-| **Manual Fixes Required** | 0 | 0 | ✅ Met |
-| **Processing Time** | <5min | ~4min | ✅ Met |
-
-### Production Readiness
-
-- ✅ **Tested with demo-create**: Pass
-- ✅ **Tested with pro-create**: Pass
-- ✅ **Test server integration**: Working
-- ✅ **Schema permissions**: Working
-- ✅ **Manual validation fallback**: Working
-- ✅ **Documentation**: Complete
-
----
-
-## Key Benefits Realized
-
-### 1. **Zero Manual Corrections**
-
-**Before**: Users often had to:
-- Fix kebab-case in lifecycles
-- Correct component: to components:
-- Fix attribute format
-- Add missing fields
-
-**After**: All automatically handled by validate-fix loop
-
-### 2. **Guaranteed Valid Output**
-
-**Before**: Generated specs might fail validation
-- Required manual debugging
-- Back-and-forth with AI
-- Frustration for users
-
-**After**: Every spec passes validation
-- No debugging needed
-- One-shot generation
-- User confidence
-
-### 3. **Comprehensive Quality Reports**
-
-**Before**: No validation details
-- Unknown quality
-- Hidden issues
-
-**After**: Detailed validation reports
-- All checks documented
-- Issues caught early
-- Quality transparent
-
-### 4. **Production-Tested Reliability**
-
-**Before**: Unknown behavior in production
-- Risky deployments
-- Potential failures
-
-**After**: Tested and validated
-- Safe for production
-- Predictable results
-- Confidence in outputs
-
----
-
-## Documentation References
-
-### Created Documentation
-
-1. **v8/README.md** (12K)
-   - Complete v8 features guide
-   - Validate-fix loop explanation
-   - Migration guide
-   - Best practices
-
-2. **default/README.md** (2.9K)
-   - v8 as default announcement
-   - Quick start guide
-   - Performance expectations
-
-3. **test-framework/docs/VALIDATE-FIX-LOOP.md** (Updated)
-   - Architecture details
-   - Usage guide
-   - Troubleshooting
-
-4. **test-framework/docs/PROMPT-ANALYSIS.md** (Existing)
-   - Prompt fitness analysis
-   - Comparison tables
-   - Recommendations
-
----
-
-## Conclusion
-
-**v8 prompts are now the default**, bringing validated spec generation to all users automatically.
-
-### Summary of Changes
-
-✅ **Created**: v8 prompts with validate-fix loop
-✅ **Promoted**: v8 to default directory
-✅ **Documented**: Comprehensive guides created
-✅ **Tested**: Production-validated with 100% success rate
-✅ **Deployed**: All users now benefit automatically
-
-### Impact
-
-- **100% validation success rate** for all generated specs
-- **Zero manual error correction** needed
-- **Production-ready quality** guaranteed
-- **Backwards compatible** with existing workflows
-- **4x processing time** but guaranteed validity
-
-### Recommendation
-
-**Use the default prompts** (v8) for all production spec generation workflows. The trade-off of longer processing time for guaranteed valid output is worth it for production use.
-
----
-
-*Date: 2025-11-22*
-*Status: Complete*
-*Impact: All users*
-*Version: 8.0.0 (Now Default)*

package/assets/prompts/core/CHANGELOG.md

@@ -1,158 +0,0 @@
-# SpecVerse Standard Prompts - Changelog
-
-## Version 7.0.0 (2025-01-XX)
-
-### 🚀 Major Enhancements
-
-#### Enhanced Data Consistency & Validation
-- **Data mapping fixes**: Comprehensive snake_case ↔ camelCase handling
-- **Multi-layer validation**: Database, API, and frontend validation patterns
-- **Type safety**: End-to-end type consistency across all layers
-- **Conflict detection**: Database-level conflict resolution functions
-
-#### Environment-Adaptive Generation
-- **Adaptive complexity**: Output scales based on target environment
-- **Progressive enhancement**: Dev → Test → Prod → Enterprise scaling
-- **Local dev focus**: Quick start scripts (start.sh) and Docker Compose
-- **Production readiness**: Zero-downtime deployments and monitoring
-
-#### Enhanced Automation
-- **Automated setup**: Complete database initialization and seeding
-- **Deployment scripts**: Environment-specific automation
-- **Health checks**: Comprehensive monitoring and debugging
-- **Error handling**: Robust error patterns with recovery
-
-### 📝 Prompt Updates
-
-#### `materialise.prompt.yaml` v7.0.0
-**NEW FEATURES:**
-- Data consistency level configuration (`strict`, `basic`, `paranoid`)
-- Multi-layer validation strategy options
-- Comprehensive error handling patterns
-- Automated setup script generation (start.sh style)
-- Database-level constraint and validation functions
-
-**BREAKING CHANGES:**
-- Now requires specification analysis phase before implementation
-- Enhanced variable set with data consistency options
-- Comprehensive quality standards for production readiness
-
-#### `realize.prompt.yaml` v7.0.0
-**NEW FEATURES:**
-- Environment-adaptive generation (development/test/production/enterprise)
-- Progressive complexity scaling based on environment needs
-- Local development environment support with Docker Compose
-- Zero-downtime deployment strategies (blue-green, canary)
-- Comprehensive monitoring and observability configurations
-
-**BREAKING CHANGES:**
-- Environment-specific output (no more one-size-fits-all)
-- New variables: `deploymentStrategy`, `databaseStrategy`, `localDevSupport`
-- Conditional template logic based on environment type
-
-#### Updated `base-terminal-prompt.md`
-**NEW FEATURES:**
-- Complete workflow examples using real guesthouse system
-- Troubleshooting section with actual issues and solutions
-- Environment-specific guidance
-- v7 prompt paths and syntax updates
-
-### 🛠️ Technical Improvements
-
-#### Quality Standards
-- **Data integrity**: Multi-layer validation with database constraints
-- **Error resilience**: Graceful degradation and recovery patterns
-- **Type mapping**: Consistent data types across boundaries
-- **Performance**: Optimized queries with proper indexing
-- **Security**: Production-grade security patterns
-
-#### Framework Support
-- **Enhanced Next.js**: Type-safe API routes, validated forms
-- **NestJS**: DTOs with class-validator, TypeORM patterns
-- **Express**: Middleware validation, centralized error handling
-- **Modern platforms**: Vercel, Netlify, serverless support
-
-### 📚 Documentation Updates
-
-#### New Guides
-- **Complete workflow**: Requirements → Specification → Implementation → Deployment
-- **Troubleshooting**: Real-world issues and solutions
-- **Best practices**: Environment-specific development patterns
-- **Migration guide**: v6 → v7 upgrade path
-
-#### Enhanced Examples
-- **Guesthouse booking system**: Complete working example
-- **Data consistency patterns**: snake_case/camelCase mapping
-- **Error handling**: Comprehensive error scenarios
-- **Environment scaling**: Dev/Prod configuration differences
-
-### 🔄 Migration from v6
-
-#### Breaking Changes
-1. **Materialise prompt**: New data consistency variables required
-2. **Realize prompt**: Environment-specific template logic
-3. **File paths**: Updated to `prompts/core/standard/v7/`
-
-#### Upgrade Steps
-1. Update prompt file paths to v7 directory
-2. Add new variables for data consistency and environment type
-3. Review generated output for enhanced error handling
-4. Test environment-adaptive deployment configurations
-
-### 🐛 Bug Fixes from Real Implementation
-
-#### Data Layer Issues (Fixed in v7)
-- **Fixed**: Database column mapping (room_id vs roomId)
-- **Fixed**: Date format conversion (ISO strings vs YYYY-MM-DD)
-- **Fixed**: API response transformation consistency
-- **Fixed**: Missing data validation at model boundaries
-
-#### Deployment Issues (Fixed in v7)
-- **Fixed**: Environment variable loading in setup scripts
-- **Fixed**: Database connection handling in development
-- **Fixed**: Missing health checks and monitoring
-- **Fixed**: Over-engineering for simple development environments
-
-#### Developer Experience (Enhanced in v7)
-- **Added**: Quick start scripts (start.sh) for immediate productivity
-- **Added**: Comprehensive error messages and debugging
-- **Added**: Environment-specific documentation
-- **Added**: Real troubleshooting scenarios
-
-### 🎯 Key Lessons Learned
-
-1. **Data consistency is critical**: v7 emphasizes proper data mapping
-2. **Environment matters**: Different environments need different complexity
-3. **Automation saves time**: Setup scripts reduce friction significantly
-4. **Error handling is essential**: Comprehensive patterns prevent issues
-5. **Local dev parity**: Development should match production patterns
-
-### 🚀 What's Next
-
-- Integration with SpecVerse inference engine v3.2.0
-- Enhanced cloud platform support (AWS, Azure, GCP)
-- Advanced monitoring and observability patterns
-- AI-powered troubleshooting assistance
-- Community-contributed prompt extensions
-
----
-
-## Version 6.0.0 (Previous Release)
-
-### Features
-- Streamlined prompt system with YAML configuration
-- Basic framework support (Next.js, NestJS, Express)
-- Infrastructure as Code generation
-- CI/CD pipeline templates
-- Security and compliance configurations
-
-### Known Issues (Resolved in v7)
-- Data mapping inconsistencies
-- Over-engineered development environments
-- Limited error handling patterns
-- Manual setup processes
-- Environment-agnostic generation
-
----
-
-*For complete documentation, see [base-terminal-prompt.md](base-terminal-prompt.md)*