Merge pull request #17 from Grazulex/copilot/fix-16

🔄 Complete documentation and examples update for first production version

Author: Grazulex

README.md

@@ -401,12 +401,12 @@ declare(strict_types=1);
 it('should fail initially - this is normal for TDDraft', function (): void {
     // This test intentionally fails to demonstrate the TDD "red" phase
     expect(false)->toBeTrue('This draft needs implementation!');
-})->group('tddraft');
+})->group('tddraft', 'feature', 'example-red-phase');
 
 it('can be promoted when ready', function (): void {
     // When this passes, you can promote it to your main test suite
     expect(true)->toBeTrue();
-})->group('tddraft');
+})->group('tddraft', 'feature', 'example-green-phase');
 ```
 
 ## 📚 Documentation

docs/best-practices.md

@@ -169,35 +169,37 @@ it('allows user registration with valid data', function (): void {
     ]);
 
     $response->assertStatus(201);
-})->group('tddraft');
+})->group('tddraft', 'feature', 'tdd-20250718142530-Abc123');
 ```
 
-### Use the `tddraft` Group
+### Use the `tddraft` Group with References
 
-Always mark draft tests with the appropriate group:
+Always mark draft tests with the appropriate groups including the unique reference for tracking:
 
 ```php
 it('describes the behavior', function (): void {
     // Test implementation
-})->group('tddraft');
+})->group('tddraft', 'feature', 'tdd-20250718142530-Abc123');
 ```
 
+**Best Practice:** Use `php artisan tdd:make` to automatically generate tests with proper grouping and unique references. Manual test creation should follow the same pattern.
+
 ### Write Descriptive Test Names
 
 Test names should read like specifications:
 
 ```php
 it('prevents registration with duplicate email', function (): void {
     // ...
-})->group('tddraft');
+})->group('tddraft', 'feature', 'tdd-20250718142530-Abc123');
 
 it('sends welcome email after successful registration', function (): void {
     // ...
-})->group('tddraft');
+})->group('tddraft', 'feature', 'tdd-20250718142531-Def456');
 
 it('redirects to dashboard after login', function (): void {
     // ...
-})->group('tddraft');
+})->group('tddraft', 'feature', 'tdd-20250718142532-Ghi789');
 ```
 
 ### Focus on One Behavior Per Test
@@ -214,12 +216,12 @@ it('validates email format during registration', function (): void {
 
     $response->assertStatus(422)
         ->assertJsonValidationErrors(['email']);
-})->group('tddraft');
+})->group('tddraft', 'feature', 'tdd-20250718142534-Mno345');
 
 // Avoid: Testing multiple behaviors
 it('handles registration validation', function (): void {
     // Don't test email, password, name validation all in one test
-})->group('tddraft');
+})->group('tddraft', 'feature', 'tdd-20250718142535-Pqr678');
 ```
 
 ## TDD Workflow

docs/commands.md

@@ -460,4 +460,134 @@ pest --testsuite=tddraft --group=feature
 
 # Run all unit drafts
 pest --testsuite=tddraft --group=unit
-```
+```
+
+## tdd:promote
+
+Promote a TDDraft test to the CI test suite (tests/Feature or tests/Unit) with automated file management and reference preservation.
+
+### Usage
+
+```bash
+# Basic promotion (auto-detects target directory based on test type)
+php artisan tdd:promote tdd-20250718142530-Abc123
+
+# Promote to specific directory
+php artisan tdd:promote tdd-20250718142530-Abc123 --target=Unit
+php artisan tdd:promote tdd-20250718142530-Abc123 --target=Feature
+
+# Create new file with custom name
+php artisan tdd:promote tdd-20250718142530-Abc123 --new-file=UserRegistrationTest
+
+# Append to existing file
+php artisan tdd:promote tdd-20250718142530-Abc123 --file=ExistingTest.php
+
+# Specify custom class name
+php artisan tdd:promote tdd-20250718142530-Abc123 --class=CustomTestClass
+
+# Keep original draft file after promotion
+php artisan tdd:promote tdd-20250718142530-Abc123 --keep-draft
+
+# Force overwrite without confirmation
+php artisan tdd:promote tdd-20250718142530-Abc123 --force
+```
+
+### Options
+
+- `reference` (required): The unique reference ID of the TDDraft test to promote
+- `--target=Feature|Unit`: Target directory (Feature or Unit). If not specified, uses the test type from the draft
+- `--file=`: Existing file to append the test to (optional)
+- `--new-file=`: New file name to create (optional, without .php extension)
+- `--class=`: Custom test class name (optional)
+- `--force`: Overwrite existing files without confirmation
+- `--keep-draft`: Keep the original draft file after promotion
+
+### What it Does
+
+1. **Finds Draft Test**: Locates the TDDraft test file using the unique reference
+2. **Parses Test Content**: Extracts test metadata, content, and structure
+3. **Determines Target**: Automatically selects target directory based on test type or provided options
+4. **Handles File Operations**: Creates new files or appends to existing ones as specified
+5. **Updates Test Content**: 
+   - Removes TDDraft-specific comments and metadata
+   - Removes `tddraft` group but preserves the unique reference for audit trails
+   - Updates class names and namespaces if needed
+6. **Updates Status**: Marks test as "promoted" in the status tracking system
+7. **Cleanup**: Removes the draft file unless `--keep-draft` is specified
+
+### Promotion Process
+
+When you promote a test, the following transformations occur:
+
+**Before Promotion (Draft):**
+```php
+/**
+ * TDDraft Test: User can register
+ * 
+ * Reference: tdd-20250718142530-Abc123
+ * Type: feature
+ * Created: 2025-07-18 14:25:30
+ */
+
+it('user can register', function (): void {
+    // Test implementation
+})
+->group('tddraft', 'feature', 'tdd-20250718142530-Abc123')
+->todo('Implement the test scenario for: user can register');
+```
+
+**After Promotion (CI Suite):**
+```php
+it('user can register', function (): void {
+    // Test implementation  
+})
+->group('feature', 'tdd-20250718142530-Abc123'); // Reference preserved for audit
+```
+
+### Target Directory Selection
+
+- **Auto-detection**: Uses the `Type:` field from the draft test metadata
+- **Manual override**: Use `--target=Feature` or `--target=Unit` to specify
+- **Path creation**: Automatically creates target directories if they don't exist
+
+### Example Output
+
+```
+📋 Found draft test: tests/TDDraft/UserCanRegisterTest.php
+✅ Successfully promoted test to: tests/Feature/UserCanRegisterTest.php
+🎯 Test class: UserCanRegisterTest
+🗑️  Removed draft file: tests/TDDraft/UserCanRegisterTest.php
+```
+
+### Advanced Promotion Examples
+
+```bash
+# Organize promoted tests in subdirectories
+php artisan tdd:promote tdd-20250718142530-Abc123 --target=Feature --new-file=Auth/UserRegistrationTest
+
+# Append multiple draft tests to a comprehensive test file
+php artisan tdd:promote tdd-20250718142530-Abc123 --file=UserManagementTest.php
+php artisan tdd:promote tdd-20250718142531-Def456 --file=UserManagementTest.php
+
+# Keep drafts for reference during code review
+php artisan tdd:promote tdd-20250718142530-Abc123 --keep-draft
+
+# Batch promotion workflow
+php artisan tdd:list --type=feature  # Find tests ready for promotion
+php artisan tdd:promote tdd-20250718142530-Abc123
+php artisan tdd:promote tdd-20250718142531-Def456
+```
+
+### Error Handling
+
+- **Test Not Found**: Shows error if the reference doesn't match any draft test
+- **File Conflicts**: Asks for confirmation before overwriting existing files (unless `--force` is used)
+- **Invalid Options**: Validates option combinations and shows helpful error messages
+- **Directory Creation**: Automatically creates target directories if they don't exist
+
+### Integration with Status Tracking
+
+The promote command automatically:
+- Updates the test status to "promoted"
+- Maintains the status history for audit trails
+- Preserves the unique reference in the promoted test for lineage tracking

docs/configuration.md

@@ -146,7 +146,9 @@ Status tracking is automatically enabled and works with the `tdd:test` command:
 php artisan tdd:test
 
 # Status is tracked in tests/TDDraft/.status.json
-# View status through tdd:list command (coming in future versions)
+# View status through tdd:list command
+php artisan tdd:list
+php artisan tdd:list --details
 ```
 
 **Benefits of Status Tracking:**

examples/basic-usage.php

@@ -284,16 +284,16 @@
 echo "10. Configuration Options\n";
 echo "-------------------------\n";
 echo "The config/tddraft.php file contains:\n";
-echo "  - Package enablement settings\n";
-echo "  - Default timeouts and retry attempts\n";
-echo "  - Caching configuration\n";
-echo "  - Logging settings\n\n";
+echo "  - Status tracking configuration (NEW)\n";
+echo "  - Test result history management\n";
+echo "  - File path settings for status storage\n";
+echo "  - Environment-specific controls\n\n";
 
 echo "Environment variables:\n";
-echo "  LARAVEL_TDDRAFT_ENABLED=true\n";
-echo "  LARAVEL_TDDRAFT_LOGGING_ENABLED=false\n";
-echo "  LARAVEL_TDDRAFT_LOG_CHANNEL=stack\n";
-echo "  LARAVEL_TDDRAFT_LOG_LEVEL=info\n\n";
+echo "  LARAVEL_TDDRAFT_STATUS_TRACKING_ENABLED=true\n";
+echo "  LARAVEL_TDDRAFT_STATUS_FILE=tests/TDDraft/.status.json\n";
+echo "  LARAVEL_TDDRAFT_TRACK_HISTORY=true\n";
+echo "  LARAVEL_TDDRAFT_MAX_HISTORY=50\n\n";
 
 echo "✅ That's the complete TDDraft workflow!\n";
 echo "Key benefits:\n";