--- allowed-tools: all description: **ANALYZE PHP annotation coverage** with comprehensive bidirectional linkage validation using parallel agents (analysis only - no test execution) intensity: ⚡⚡⚡ pattern: 📝📝📝 --- # 📝📝📝 CRITICAL ANNOTATION ANALYSIS: COMPREHENSIVE BIDIRECTIONAL LINKAGE VALIDATION! 📝📝📝 **THIS IS NOT TEST EXECUTION - THIS IS COMPREHENSIVE ANNOTATION COVERAGE ANALYSIS!** **🚨 NOTE: This command analyzes existing annotations - it does NOT execute tests! 🚨** ## 🚨 ZERO TOLERANCE ENFORCEMENT **MANDATORY - ALL annotation validation must achieve PERFECT analysis:** ### Success Criteria (ALL must be met) - ✅ **0 Failed Validations** - All annotation checks must pass - ✅ **0 Errors** - No parsing or analysis errors allowed - ✅ **0 Warnings** - Annotation warnings are treated as failures - ✅ **0 Broken Links** - All annotation references must be valid - ✅ **0 Orphaned Methods** - All methods need corresponding annotations - ✅ **100% Bidirectional** - All @Verified must have matching @TestedBy - ✅ **0 Syntax Errors** - Annotation syntax must be perfect ### Failure Response Protocol When ANY issue is detected: 1. **STOP** - Do not proceed to next analysis steps 2. **REPORT** - List all annotation issues with file:line references 3. **FIX** - Resolve ALL annotation issues before continuing 4. **VERIFY** - Re-run validation to confirm 100% clean analysis ### Exit Codes - `0` = Perfect annotation analysis (no broken links, no orphans) - `1` = Any validation failure, broken link, or missing annotation - `2` = Configuration or annotation system error --- When you run `\/test annotation`, you are REQUIRED to: 1. **SCAN** all source methods and test methods for @Verified and @TestedBy annotations 2. **VALIDATE** bidirectional method-to-test-case linkage at the method level 3. **VERIFY** that source methods have @Verified annotations pointing to specific test methods 4. **ENSURE** that test methods have @TestedBy annotations pointing to specific source methods 5. **FIX** annotation issues automatically with safe mode validation 6. **REPORT** comprehensive validation results with actionable recommendations 7. **USE MULTIPLE AGENTS** for parallel annotation processing with Task tool **FORBIDDEN BEHAVIORS:** - ❌ "Basic annotation check" → NO! Use comprehensive method-level bidirectional validation! - ❌ "Class-level annotation validation" → NO! Must validate at method level! - ❌ "Skip method-to-test-case mapping" → NO! Method-level linkage analysis required! - ❌ "Ignore orphaned methods" → NO! All methods must have corresponding test annotations! - ❌ "Single-threaded validation" → NO! Use parallel agent coordination! - ❌ "Generic annotation output" → NO! Method-specific parsing and reporting! - ❌ "Bash functions instead of Task tool" → NO! Use proper Task tool agents! **MANDATORY WORKFLOW:** ``` 1. PHP annotation system detection → Identify annotation-automation.php 2. IMMEDIATELY spawn 5 agents for parallel method-level validation using Task tool 3. Method discovery → Find all public methods in source classes 4. Annotation discovery → Find all @Verified and @TestedBy annotations at method level 5. Parallel validation → Run method-to-test-case linkage validation across multiple agents 6. Bidirectional linkage analysis → Validate method-level consistency 7. VERIFY results → Ensure all methods have valid test linkages and coverage complete ``` ## TASK TOOL AGENT SPAWNING (MANDATORY) I'll spawn 5 specialized agents using Task tool for comprehensive annotation analysis: ### Test Scanner Agent: ```markdown test-annotation-scanner<\/parameter> Scan test files for @TestedBy annotations<\/parameter> You are the Test Scanner Agent for PHP annotation analysis. Your responsibilities: 1. Discover all PHP test files in the project (typically in test\/, tests\/, or Cases\/ directories) 2. Scan each test file for @TestedBy annotations on test methods 3. Extract test method names and their corresponding @TestedBy target methods 4. Identify test files with missing @TestedBy annotations 5. Generate comprehensive test file inventory with annotation status MANDATORY ANNOTATION SCANNING: You MUST actually scan test files for annotation patterns: - Use Glob to find all PHP test files: **\/*Test.php, **\/test\/**\/*.php, **\/tests\/**\/*.php - Use Grep to search for @TestedBy annotations and test methods - Parse annotation syntax: @TestedBy(method="ClassName::methodName") - Map test methods to their target source methods - Report orphaned test methods (tests without @TestedBy annotations) MANDATORY RESULT TRACKING: - You MUST save analysis results to \/tmp\/test-annotation-scanner-results.json - Include success: true\/false, test_files_found, annotations_discovered, orphaned_tests - Document all discovered test methods and their annotation status - Report any file access failures or annotation parsing errors CRITICAL: Comprehensive test annotation scanning is required for bidirectional validation.<\/parameter> <\/invoke> <\/function_calls> ``` ### Source Annotation Analyzer: ```markdown source-annotation-analyzer<\/parameter> Analyze source files for @Verified annotations<\/parameter> You are the Source Annotation Analyzer for PHP source file analysis. Your responsibilities: 1. Discover all PHP source files in the project (typically in src\/, app\/, or lib\/ directories) 2. Scan each source file for @Verified annotations on public methods 3. Extract method signatures and their corresponding @Verified target test methods 4. Identify source methods with missing @Verified annotations 5. Validate annotation syntax and format correctness MANDATORY SOURCE ANALYSIS: You MUST actually analyze source files for annotation patterns: - Use Glob to find all PHP source files: **\/src\/**\/*.php, **\/app\/**\/*.php, **\/lib\/**\/*.php - Use Grep to search for @Verified annotations and public methods - Parse annotation syntax: @Verified(by="TestClass::testMethodName") - Map source methods to their corresponding test methods - Report orphaned source methods (methods without @Verified annotations) - Validate bidirectional linkage consistency MANDATORY RESULT TRACKING: - You MUST save analysis results to \/tmp\/source-annotation-analyzer-results.json - Include success: true\/false, source_files_found, verified_methods, unverified_methods - Document method signatures and their annotation status - Only execute after verifying source file accessibility CRITICAL: Complete source method annotation analysis is required for coverage metrics.<\/parameter> <\/invoke> <\/function_calls> ``` ### Annotation Generator: ```markdown annotation-generator<\/parameter> Generate missing annotations automatically<\/parameter> You are the Annotation Generator for PHP annotation completion. Your responsibilities: 1. Read results from Test Scanner Agent and Source Annotation Analyzer 2. Identify missing @Verified annotations on source methods 3. Identify missing @TestedBy annotations on test methods 4. Generate properly formatted annotation suggestions 5. Create annotation patches for automatic application MANDATORY ANNOTATION GENERATION: You MUST actually generate missing annotations: - Load \/tmp\/test-annotation-scanner-results.json and \/tmp\/source-annotation-analyzer-results.json - Cross-reference source methods with test methods - Generate @Verified annotations for source methods pointing to existing test methods - Generate @TestedBy annotations for test methods pointing to source methods - Create diff patches for annotation additions - Validate annotation syntax and formatting MANDATORY RESULT TRACKING: - You MUST save generation results to \/tmp\/annotation-generator-results.json - Include success: true\/false, annotations_generated, patch_files_created, syntax_validated - Document specific annotation additions and their target methods - Only execute after both scanner agents confirm completion CRITICAL: Automatic annotation generation requires cross-referencing both source and test analysis.<\/parameter> <\/invoke> <\/function_calls> ``` ### Bidirectional Validator: ```markdown bidirectional-validator<\/parameter> Validate annotation consistency and linkages<\/parameter> You are the Bidirectional Validator for PHP annotation consistency checking. Your responsibilities: 1. Read results from all other annotation agents 2. Validate bidirectional linkage between @Verified and @TestedBy annotations 3. Check for broken links (annotations pointing to non-existent methods) 4. Identify inconsistencies between source and test annotations 5. Generate comprehensive validation report with issues and recommendations MANDATORY BIDIRECTIONAL VALIDATION: You MUST actually validate annotation consistency: - Load all agent result files from \/tmp\/ - Cross-validate method linkages in both directions - Check that every @Verified(by="TestClass::testMethod") has corresponding @TestedBy(method="SourceClass::sourceMethod") - Identify orphaned annotations (pointing to non-existent methods) - Calculate coverage metrics (percentage of methods with annotations) - Generate actionable fix recommendations MANDATORY RESULT TRACKING: - You MUST save validation results to \/tmp\/bidirectional-validator-results.json - Include success: true\/false, linkage_validated, broken_links_found, coverage_percentage - Document specific inconsistencies and orphaned annotations - Only execute after all generator agents complete their work CRITICAL: Comprehensive consistency validation ensures annotation reliability.<\/parameter> <\/invoke> <\/function_calls> ``` ### Annotation Reporter: ```markdown annotation-reporter<\/parameter> Generate comprehensive annotation coverage report<\/parameter> You are the Annotation Reporter for PHP annotation documentation. Your responsibilities: 1. Read results from all other annotation agents 2. Generate comprehensive annotation coverage report 3. Create method-level annotation statistics and metrics 4. Document annotation best practices and patterns found 5. Generate actionable improvement recommendations MANDATORY ANNOTATION REPORTING: You MUST actually generate comprehensive reports: - Load all agent result files from \/tmp\/ - Compile comprehensive annotation coverage statistics - Generate method-level coverage report with gaps identified - Create visual representation of annotation linkages - Document common annotation patterns and anti-patterns found - Generate prioritized list of annotation improvements - Create summary report with before\/after metrics MANDATORY RESULT TRACKING: - You MUST save reporting results to \/tmp\/annotation-reporter-results.json - Include success: true\/false, report_generated, metrics_calculated, recommendations_provided - Generate final comprehensive annotation coverage report - Only execute after bidirectional validator completes validation CRITICAL: Clear, actionable reporting provides guidance for annotation improvements.<\/parameter> <\/invoke> <\/function_calls> ``` ## AGENT RESULT VERIFICATION (MANDATORY) After spawning all 5 annotation agents, you MUST verify their results: ```bash # MANDATORY: Verify all agents completed successfully AGENT_RESULTS_DIR="\/tmp" AGENT_FILES=("test-annotation-scanner-results.json" "source-annotation-analyzer-results.json" "annotation-generator-results.json" "bidirectional-validator-results.json" "annotation-reporter-results.json") for result_file in "${AGENT_FILES[@]}"; do FULL_PATH="$AGENT_RESULTS_DIR\/$result_file" if [ -f "$FULL_PATH" ]; then # Use jq to parse agent results AGENT_SUCCESS=$(jq -r '.success \/\/ false' "$FULL_PATH" 2>\/dev\/null || echo 'false') if [ "$AGENT_SUCCESS" != "true" ]; then echo "❌ CRITICAL: Annotation analysis agent failed to complete successfully" echo " Failed agent result: $result_file" echo " Check agent logs for failure details" exit 1 fi else echo "❌ CRITICAL: Missing annotation analysis agent result file: $result_file" echo " Agent may have failed to complete or save results" exit 1 fi done echo "✅ All annotation analysis agents completed successfully" ``` ## COMPREHENSIVE ANNOTATION ANALYSIS EXECUTION (MANDATORY) After agent coordination, you MUST execute annotation analysis validation: ```bash # Load final annotation analysis results if [ -f "\/tmp\/annotation-reporter-results.json" ]; then echo "📝 Generating comprehensive annotation coverage report..." # Extract coverage metrics from final report COVERAGE_PERCENTAGE=$(jq -r '.coverage_percentage \/\/ 0' "\/tmp\/annotation-reporter-results.json" 2>\/dev\/null || echo '0') VERIFIED_METHODS=$(jq -r '.verified_methods \/\/ 0' "\/tmp\/annotation-reporter-results.json" 2>\/dev\/null || echo '0') UNVERIFIED_METHODS=$(jq -r '.unverified_methods \/\/ 0' "\/tmp\/annotation-reporter-results.json" 2>\/dev\/null || echo '0') BROKEN_LINKS=$(jq -r '.broken_links_found \/\/ 0' "\/tmp\/annotation-reporter-results.json" 2>\/dev\/null || echo '0') echo "📊 Annotation Coverage Analysis Results:" echo " Coverage Percentage: $COVERAGE_PERCENTAGE%" echo " Methods with @Verified annotations: $VERIFIED_METHODS" echo " Methods missing @Verified annotations: $UNVERIFIED_METHODS" echo " Broken annotation links: $BROKEN_LINKS" # Validate minimum coverage requirements if [ "$COVERAGE_PERCENTAGE" -lt 80 ]; then echo "⚠️ WARNING: Annotation coverage below recommended 80% threshold" echo " Consider adding @Verified\/@TestedBy annotations to improve coverage" fi if [ "$BROKEN_LINKS" -gt 0 ]; then echo "⚠️ WARNING: Found $BROKEN_LINKS broken annotation links" echo " Review and fix annotations pointing to non-existent methods" fi echo "✅ Annotation analysis completed successfully" else echo "❌ CRITICAL: Final annotation report not found" echo " Annotation analysis may have failed to complete" exit 1 fi ``` 🛑 **MANDATORY ANNOTATION VALIDATION PROTOCOL** 🛑 1. **SPAWN ALL 5 AGENTS IMMEDIATELY** using Task tool for parallel processing 2. **VERIFY AGENT RESULTS** using the mandatory verification script 3. **EXECUTE ANNOTATION ANALYSIS** to generate coverage metrics and reports 4. **VALIDATE COVERAGE** against minimum thresholds and quality standards Execute comprehensive annotation validation with ZERO tolerance for incomplete linkage analysis. **FORBIDDEN SHORTCUT PATTERNS:** - "Basic annotation scan is sufficient" → NO, comprehensive validation required - "Skip slow validation for speed" → NO, all annotations must be validated - "Linkage reports are optional" → NO, mandatory linkage analysis - "Manual annotation analysis is fine" → NO, automated analysis required - "Single agent validation is faster" → NO, parallel validation mandatory - "Bash functions instead of Task tool" → NO, use proper Task tool agents You are validating annotations for: $ARGUMENTS Let me ultrathink about comprehensive annotation validation with parallel agent coordination. 🚨 **REMEMBER: Annotations are the foundation of test-source linkage reliability!** 🚨 **YOU ARE NOT DONE UNTIL:** - ✅ All 5 agents have been spawned using Task tool and completed their analysis - ✅ All public methods discovered and scanned for annotations - ✅ Method-level bidirectional linkage analyzed with gap identification - ✅ All source methods have @Verified annotations pointing to specific test methods - ✅ All test methods have @TestedBy annotations pointing to specific source methods - ✅ Orphaned methods identified and reported - ✅ Invalid method-to-test-case mappings analyzed with root cause identification - ✅ Method-level coverage metrics collected and reported - ✅ Actionable recommendations provided for method annotation improvements **Method-Level Annotation Patterns:** **Source Method Annotation Example:** ```php class UserService { \/** * @Verified(by="UserServiceTest::testCreateUser") * @param array $userData * @return User *\/ public function createUser(array $userData): User { \/\/ Implementation } } ``` **Test Method Annotation Example:** ```php class UserServiceTest extends TestCase { \/** * @TestedBy(method="UserService::createUser") * @covers UserService::createUser *\/ public function testCreateUser(): void { \/\/ Test implementation } } ``` **Anti-Patterns to Avoid:** - ❌ Running validation without method-level bidirectional linkage analysis (incomplete validation) - ❌ Validating at class level instead of method level (insufficient granularity) - ❌ Ignoring orphaned methods without corresponding test annotations (quality compromise) - ❌ Single-threaded validation without parallelization (performance issue) - ❌ Generic validation without method-specific PHP optimization (suboptimal) - ❌ Skipping method-level coverage analysis or quality metrics (missed insights) - ❌ No automated method annotation fixing or actionable recommendations (missed improvements) - ❌ Using bash functions instead of Task tool agents (not real parallelism) **Final Verification:** Before completing method-level annotation validation: - Have I spawned all 5 agents using Task tool for true parallel processing? - Have I discovered and scanned all public source methods for @Verified annotations? - Have I discovered and scanned all test methods for @TestedBy annotations? - Are method-to-test-case linkage reports generated with gap analysis? - Have I identified and reported all orphaned methods without corresponding annotations? - Are method-level fix recommendations provided with safe mode options? - Do I have comprehensive monitoring setup for continuous method-level validation? **Final Commitment:** - **I will**: Use Task tool for all 5 agent spawning operations with proper parallel execution - **I will**: Validate all method-level annotations with comprehensive bidirectional linkage analysis - **I will**: Discover and scan all public source methods for @Verified annotations - **I will**: Discover and scan all test methods for @TestedBy annotations - **I will**: Use parallel agents for optimal method-level validation performance - **I will**: Provide detailed method-to-test-case gap analysis and actionable recommendations - **I will**: Validate method annotation quality and suggest improvements - **I will**: Generate comprehensive method-level reports with monitoring capabilities - **I will NOT**: Skip method-level linkage analysis or quality validation - **I will NOT**: Ignore orphaned methods or broken method-to-test-case linkages - **I will NOT**: Use single-threaded validation without parallelization - **I will NOT**: Use bash functions instead of proper Task tool agents - **I will NOT**: Provide generic reports without method-specific actionable insights **REMEMBER:** This is METHOD-LEVEL ANNOTATION VALIDATION mode - comprehensive method-level annotation analysis with bidirectional linkage validation, quality metrics, and automated fixing using 5 parallel Task tool agents. The goal is to ensure every source method has a corresponding @Verified annotation pointing to a specific test method, and every test method has a corresponding @TestedBy annotation pointing to a specific source method. Executing comprehensive annotation validation protocol with parallel agent coordination...