feat(assessors): support AGENTS.md and @ references in CLAUDEmdAssessor

[chambridge]

Description

Add comprehensive support for cross-tool compatibility and flexible configuration:

This enhancement enables repositories to:

1. Share configuration across multiple AI coding assistants
2. Use flexible @ reference indirection for minimal CLAUDE.md files
3. Maintain backward compatibility with existing CLAUDE.md workflows

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Refactoring (no functional changes)
• Performance improvement
• Test coverage improvement

Related Issues

Fixes #244

Changes Made

• Support CLAUDE.md as symlink to AGENTS.md
• Support @ reference syntax (@AGENTS.md) for content indirection
• Accept AGENTS.md as alternative to CLAUDE.md (90/100 score)
• Detect cross-tool compatibility when both files present
• Implement path traversal security protection (reject ../ and absolute paths)
• Add 14 comprehensive unit tests including security validation
• Add type hints and performance improvements

Testing

• Unit tests pass (pytest)
• Integration tests pass
• Manual testing performed
• No new warnings or errors

Checklist

• My code follows the project's code style
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published

Screenshots (if applicable)

Additional Notes

[github-actions]

📈 Test Coverage Report

Branch	Coverage
This PR	62.5%
Main	62.3%
Diff	✅ +0.2%

---

Coverage calculated from unit tests only

[github-actions]

AgentReady Code Review - PR #265

Summary

Status: ✅ APPROVE with minor suggestions
Score Impact: Positive - enhances attribute assessment capability
Security: ✅ PASS - Path traversal protection implemented correctly

This PR adds comprehensive support for AGENTS.md and @ reference syntax to the CLAUDEmdAssessor, enabling cross-tool compatibility while maintaining security.

---

🎯 AgentReady Attribute Compliance

✅ Strengths

1. Test Coverage (test_coverage) - Score: 95/100

• 14 comprehensive unit tests covering all new functionality
• Security test cases for path traversal prevention
• Edge cases well covered (symlinks, @ references, missing files)
• Test file: tests/unit/test_assessors_documentation.py (+441 lines)

2. Type Annotations (type_annotations) - Score: 100/100

• All new methods have proper type hints
• Uses modern Python 3.11+ syntax
• Return types explicitly declared

3. Inline Documentation (inline_documentation) - Score: 100/100

• Comprehensive docstrings on all new methods
• Security considerations documented
• Pass criteria clearly explained

4. Code Complexity (code_complexity) - Score: 90/100

• Well-factored with helper methods
• Main assess() method is complex but readable
• Consider: Could extract symlink detection logic to helper method

5. Standard Project Layout (standard_layout) - Score: 100/100

• Tests properly organized in tests/unit/
• Follows existing project structure conventions

---

🔒 Security Analysis

✅ Excellent Path Traversal Protection

Location: src/agentready/assessors/documentation.py:216-220

Assessment:

• ✅ Correctly rejects ../ path traversal attempts
• ✅ Correctly rejects absolute paths
• ✅ Validated by comprehensive security tests
• ✅ Defense-in-depth: Path.resolve validates file exists within repo

---

💎 Code Quality

✅ Excellent Practices

1. Error Handling - Gracefully handles FileNotFoundError, OSError, UnicodeDecodeError
2. TOCTOU Prevention - Uses try-except around file reads instead of existence checks
3. Readability - Clear variable names, user-friendly evidence messages
4. Backwards Compatibility - Maintains existing behavior, no breaking changes

📝 Minor Suggestions (Optional)

1. Extract symlink detection to helper method (readability)
2. Cache AGENTS.md read to avoid duplicate I/O (performance)
3. Add inline comment for regex pattern (documentation)

---

🧪 Testing Assessment

✅ Comprehensive Test Coverage

Test Categories:

1. ✅ Happy paths (CLAUDE.md exists, symlinks, @ references)
2. ✅ Edge cases (minimal files, missing references, subdirectories)
3. ✅ Security (path traversal, absolute paths)
4. ✅ Cross-tool compatibility (both files present)
5. ✅ Helper method testing

Test Quality: 10/10

• Clear test names describe scenarios
• Proper test isolation using tmp_path fixtures
• Assertions verify both score and evidence messages
• Security tests validate rejection of malicious paths

---

📊 Scoring Logic Review

✅ Well-Designed Scoring Strategy

Scenario	Score	Reasoning
CLAUDE.md >50 bytes	100	Perfect - primary file exists
CLAUDE.md symlink to AGENTS.md	100	Perfect - cross-tool compatible
CLAUDE.md with @AGENTS.md	100	Perfect - indirection supported
AGENTS.md only	90	Good but missing CLAUDE.md
CLAUDE.md <50 bytes, invalid @	25	Partial credit
Neither file exists	0	Fail - no configuration

Assessment: Scoring is fair, incentivizes best practices, and provides partial credit appropriately.

---

✅ Final Verdict

Recommendation: APPROVE

This PR demonstrates excellent software engineering practices:

✅ Security: Robust path traversal protection
✅ Testing: Comprehensive coverage with security validation
✅ Code Quality: Well-factored, readable, maintainable
✅ Documentation: Clear docstrings and user guidance
✅ Backwards Compatibility: No breaking changes
✅ AgentReady Attributes: High compliance across all measured attributes

Risk Assessment: LOW

• No breaking changes
• Security considerations properly handled
• Extensive test coverage validates behavior
• Error handling prevents crashes

---

📈 AgentReady Score Impact

Before: CLAUDEmdAssessor only recognized CLAUDE.md
After: Supports AGENTS.md, symlinks, @ references

Impact: Enables more flexible repository configurations and encourages cross-tool compatibility

Estimated Score Improvement: +5-10 points for repos with AGENTS.md

---

Reviewed by: AgentReady Code Review (Claude Sonnet 4.5)
Review Date: 2026-01-16
PR: #265

[github-actions]

🎉 This PR is included in version 2.23.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀