agentic-code 0.5.1

package/.agents/rules/core/testing-strategy.md

@@ -0,0 +1,230 @@
+# Test Strategy: ROI-Based Selection
+
+## Core Principle: Maximum Coverage, Minimum Tests
+
+**Philosophy**: 10 reliable tests > 100 unmaintained tests
+
+Quality over quantity - focus resources on high-value tests that provide maximum coverage with minimum maintenance burden.
+
+## ROI Calculation Framework
+
+### ROI Formula
+
+```
+ROI Score = (Business Value × User Frequency + Legal Requirement × 10 + Defect Detection)
+            / (Creation Cost + Execution Cost + Maintenance Cost)
+```
+
+### Value Components
+
+**Business Value** (0-10 scale):
+- 10: Revenue-critical (payment processing, checkout)
+- 8-9: Core business features (user registration, data persistence)
+- 5-7: Important secondary features (search, filtering)
+- 2-4: Nice-to-have features (UI enhancements)
+- 0-1: Cosmetic features
+
+**User Frequency** (0-10 scale):
+- 10: Every user, every session (authentication)
+- 8-9: >80% of users regularly
+- 5-7: 50-80% of users occasionally
+- 2-4: <50% of users rarely
+- 0-1: Edge case users only
+
+**Legal Requirement** (boolean → 0 or 1):
+- 1: Legally mandated (GDPR compliance, data protection)
+- 0: Not legally required
+
+**Defect Detection** (0-10 scale):
+- 10: High likelihood of catching critical bugs
+- 5-7: Moderate likelihood of catching bugs
+- 0-4: Low likelihood (simple logic, well-tested patterns)
+
+### Cost Components
+
+**Test Level Cost Table**:
+
+| Test Level  | Creation Cost | Execution Cost | Maintenance Cost | Total Cost |
+|-------------|---------------|----------------|------------------|------------|
+| Unit        | 1             | 1              | 1                | 3          |
+| Integration | 3             | 5              | 3                | 11         |
+| E2E         | 10            | 20             | 8                | 38         |
+
+**Cost Rationale**:
+- **Unit Tests**: Fast to write, fast to run, rarely break from refactoring
+- **Integration Tests**: Moderate setup, slower execution, moderate maintenance
+- **E2E Tests**: Complex setup, very slow execution, high brittleness (12x more expensive than unit tests)
+
+### ROI Calculation Examples
+
+**Example 1: Payment Processing Integration Test**
+```
+Business Value: 10 (revenue-critical)
+User Frequency: 9 (90% of users)
+Legal Requirement: 0
+Defect Detection: 8 (high complexity)
+
+ROI = (10 × 9 + 0 + 8) / 11 = 98 / 11 = 8.9
+Decision: HIGH ROI → Generate this test
+```
+
+**Example 2: UI Theme Toggle E2E Test**
+```
+Business Value: 2 (cosmetic feature)
+User Frequency: 5 (50% of users)
+Legal Requirement: 0
+Defect Detection: 3 (simple logic)
+
+ROI = (2 × 5 + 0 + 3) / 38 = 13 / 38 = 0.34
+Decision: LOW ROI → Skip this E2E test (consider unit test instead)
+```
+
+**Example 3: GDPR Data Deletion E2E Test**
+```
+Business Value: 8 (critical compliance)
+User Frequency: 1 (rare user action)
+Legal Requirement: 1 (legally mandated)
+Defect Detection: 9 (high consequences if broken)
+
+ROI = (8 × 1 + 1 × 10 + 9) / 38 = 27 / 38 = 0.71
+Decision: MEDIUM ROI → Generate (legal requirement justifies cost)
+```
+
+## Critical User Journey Definition
+
+Tests with HIGH priority regardless of strict ROI calculation:
+
+### Mandatory Coverage Areas
+
+1. **Revenue-Impacting Flows**
+   - Payment processing end-to-end
+   - Checkout and order completion
+   - Subscription management
+   - Purchase confirmation and receipts
+
+2. **Legally Required Flows**
+   - GDPR data deletion/export
+   - User consent management
+   - Data protection compliance
+   - Regulatory audit trails
+
+3. **High-Frequency Core Functionality**
+   - User authentication/authorization (>80% of users)
+   - Core CRUD operations for primary entities
+   - Critical business workflows
+   - Data integrity for primary data models
+
+**Budget Exception**: Critical User Journeys may exceed standard budget limits with explicit justification.
+
+## Test Selection Guidelines
+
+### Selection Thresholds
+
+**Integration Tests**:
+- ROI > 3.0: Strong candidate
+- ROI 1.5-3.0: Consider based on available budget
+- ROI < 1.5: Skip or convert to unit test
+
+**E2E Tests**:
+- ROI > 2.0: Strong candidate
+- ROI 1.0-2.0: Consider if Critical User Journey
+- ROI < 1.0: Skip (too expensive relative to value)
+
+### Push-Down Analysis
+
+Before generating higher-level test, ask:
+
+1. **Can this be unit-tested?**
+   - YES → Generate unit test instead
+   - NO → Continue to integration test consideration
+
+2. **Already covered by integration test?**
+   - YES → Don't create E2E version
+   - NO → Consider E2E test if ROI justifies
+
+**Example**:
+- "Tax calculation accuracy" → Unit test (pure logic)
+- "Tax applied to order total" → Integration test (multiple components)
+- "User sees correct tax in checkout flow" → E2E test only if Critical User Journey
+
+## Deduplication Strategy
+
+Before generating any test:
+
+1. **Search existing test suite** for similar coverage
+2. **Check for overlapping scenarios** at different test levels
+3. **Identify redundant verifications** already covered elsewhere
+
+**Decision Matrix**:
+```
+Existing coverage found?
+  → Full coverage: Skip new test
+  → Partial coverage: Extend existing test
+  → No coverage: Generate new test
+```
+
+## Application in Test Generation
+
+### Phase 1: Candidate Enumeration
+- List all possible test scenarios
+- Assign ROI metadata to each candidate
+
+### Phase 2: ROI-Based Selection
+1. Calculate ROI for each candidate
+2. Apply deduplication checks
+3. Apply push-down analysis
+4. Sort by ROI (descending)
+
+### Phase 3: Budget Enforcement
+- Select top N tests within budget limits
+- Document budget usage
+- Report selection rationale
+
+**See**: `.agents/tasks/acceptance-test-generation.md` for detailed implementation process
+
+## Continuous Improvement
+
+### Metrics to Track
+
+1. **Selection Rate**: Tests generated / Total candidates
+   - Target: 25-35% (indicates effective filtering)
+
+2. **Average ROI**: Average ROI of generated tests
+   - Target: >3.0 for integration, >1.5 for E2E
+
+3. **Budget Utilization**: Actual tests / Budget limit
+   - Target: 80-100% (full utilization of valuable test slots)
+
+4. **Defect Detection Rate**: Bugs caught / Total tests
+   - Track over time to validate ROI predictions
+
+### Calibration
+
+Periodically review:
+- Are high-ROI tests actually catching bugs?
+- Are cost estimates accurate?
+- Do business value ratings align with stakeholder priorities?
+
+**Adjust formula weights based on empirical data**
+
+## Anti-Patterns to Avoid
+
+❌ **Gaming the System**:
+- Inflating business value scores to justify favorite tests
+- Ignoring ROI when it contradicts intuition
+- Cherry-picking ROI calculation only for preferred tests
+
+✅ **Proper Usage**:
+- Apply ROI calculation consistently to all candidates
+- Document justification when overriding ROI decisions
+- Use empirical data to calibrate scores over time
+
+❌ **Analysis Paralysis**:
+- Spending excessive time on precise ROI calculations
+- Debating single-point differences in scores
+- Treating ROI as exact science rather than decision aid
+
+✅ **Practical Application**:
+- Use ROI for relative prioritization, not absolute precision
+- Focus on order-of-magnitude differences (8.9 vs 0.34)
+- Make quick decisions for obvious high/low ROI cases

package/.agents/rules/language/general/rules.md

@@ -0,0 +1,117 @@
+# General Development Rules
+
+## Basic Principles
+
+✅ **Aggressive Refactoring**
+- Continuously improve code structure and readability
+- Make code changes in small, safe steps
+- Prioritize maintainability over initial implementation speed
+
+❌ **Unused "Just in Case" Code** - YAGNI principle
+- Don't write code for hypothetical future requirements
+- Delete unused functions, variables, and imports immediately
+- Keep codebase lean and focused on current needs
+
+## Comment Writing Rules
+
+- **Function Description Focus**: Describe what the code "does", not how it works
+- **No Historical Information**: Do not record development history in comments
+- **Timeless**: Write only content that remains valid whenever read
+- **Conciseness**: Keep explanations to necessary minimum
+- **Explain "Why"**: Comments should explain reasoning, not implementation details
+
+## Function Design
+
+**Parameter Management**
+- **0-2 parameters maximum**: Use structured data (object/struct/dict) for 3+ parameters
+  ```
+  ✅ Good: createUser({name, email, role})
+  ❌ Avoid: createUser(name, email, role, department, startDate)
+  ```
+  *Note: Use your language's idiomatic approach for grouping parameters*
+
+**Dependency Injection**
+- **Inject external dependencies explicitly**: Ensure testability and modularity
+- Pass dependencies as parameters (functions, constructors, or other language-appropriate mechanisms)
+- Avoid global state, direct instantiation, or implicit dependencies
+- Prefer interfaces/contracts over concrete implementations where applicable
+
+## Error Handling
+
+**Absolute Rule**: Error suppression prohibited. All errors must have log output and appropriate handling.
+
+**Layer-Specific Error Handling**
+- **Presentation Layer**: Convert errors to user-friendly messages, log excluding sensitive information
+- **Business Layer**: Detect business rule violations, propagate domain-specific errors
+- **Data Layer**: Convert technical errors to domain errors
+
+**Structured Logging and Sensitive Information Protection**
+Never include sensitive information in logs:
+- Passwords, tokens, API keys, secrets
+- Credit card numbers, personal identification numbers
+- Any personally identifiable information (PII)
+
+**Asynchronous Error Handling**
+- Use appropriate error handling mechanisms for your language
+- Always log and appropriately propagate errors
+- Set up global error handlers where applicable
+
+## Clean Code Principles
+
+✅ **Recommended Practices**
+- Delete unused code immediately
+- Remove debug statements and temporary logging
+- Use meaningful variable and function names
+- Keep functions small and focused on single responsibility
+
+❌ **Avoid These Practices**
+- Commented-out code (use version control for history)
+- Magic numbers without explanation
+- Deep nesting (prefer early returns)
+- Functions that do multiple unrelated things
+
+## Refactoring Techniques
+
+**Basic Policy**
+- **Small Steps**: Maintain always-working state through gradual improvements
+- **Safe Changes**: Minimize the scope of changes at once
+- **Behavior Guarantee**: Ensure existing behavior remains unchanged while proceeding
+
+**Implementation Procedure**
+1. Understand Current State
+2. Make Gradual Changes
+3. Verify Behavior
+4. Final Validation
+
+**Priority Order**
+1. Duplicate Code Removal
+2. Large Function Division
+3. Complex Conditional Branch Simplification
+4. Architecture Improvement
+
+## Performance Considerations
+
+**General Principles**
+- Measure before optimizing (avoid premature optimization)
+- Focus on algorithmic complexity over micro-optimizations
+- Consider memory usage, especially with large datasets
+- Use appropriate data structures for the use case
+
+**Resource Management**
+- Properly close files, connections, and other resources
+- Be mindful of memory leaks in long-running applications
+- Use efficient algorithms for data processing
+
+## Code Organization
+
+**File Structure**
+- Group related functionality together
+- Separate concerns (business logic, data access, presentation)
+- Use consistent naming conventions throughout the project
+- Keep configuration separate from business logic
+
+**Modularity**
+- Write small, focused modules/functions
+- Minimize dependencies between modules
+- Use clear interfaces between components
+- Follow single responsibility principle

package/.agents/rules/language/general/testing.md

@@ -0,0 +1,257 @@
+# General Testing Rules
+
+## TDD Process [MANDATORY for all code changes]
+
+**Execute this process for every code change:**
+
+### RED Phase
+1. Write test that defines expected behavior
+2. Run test
+3. Confirm test FAILS (if it passes, the test is wrong)
+
+### GREEN Phase
+1. Write MINIMAL code to make test pass
+2. Run test
+3. Confirm test PASSES
+
+### REFACTOR Phase
+1. Improve code quality
+2. Run test
+3. Confirm test STILL PASSES
+
+### VERIFY Phase [MANDATORY - 0 ERRORS REQUIRED]
+1. Execute ALL quality check commands for your language/project
+2. Fix any errors until ALL commands pass with 0 errors
+3. Confirm no regressions
+4. ENFORCEMENT: Cannot proceed with ANY errors or warnings
+
+**Exceptions (no TDD required):**
+- Pure configuration files
+- Documentation only
+- Emergency fixes (but add tests immediately after)
+
+## Basic Testing Policy
+
+### Quality Requirements
+- **Coverage**: Unit test coverage must be 80% or higher
+- **Independence**: Each test can run independently
+- **Reproducibility**: Tests are environment-independent
+
+### Coverage Requirements
+**Mandatory**: Unit test coverage must be 80% or higher
+**Metrics**: Statements, Branches, Functions, Lines
+
+### Test Types and Scope
+1. **Unit Tests**
+   - Verify behavior of individual units (functions, modules, or components)
+   - Mock all external dependencies
+   - Fast execution (milliseconds)
+
+2. **Integration Tests**
+   - Verify coordination between multiple components
+   - Use actual dependencies when appropriate
+   - Test real system interactions
+
+3. **E2E Tests (End-to-End Tests)**
+   - Verify complete user workflows across entire system
+   - Test real-world scenarios with all components integrated
+   - Validate system behavior from user perspective
+   - Ensure business requirements are met end-to-end
+
+4. **Cross-functional Verification in E2E Tests** [MANDATORY for feature modifications]
+
+   **Purpose**: Prevent regression and ensure existing features remain stable when introducing new features or modifications.
+
+   **When Required**:
+   - Adding new features that interact with existing components
+   - Modifying core business logic or workflows
+   - Changing shared resources or data structures
+   - Updating APIs or integration points
+
+   **Integration Point Analysis**:
+   - **High Impact**: Changes to core process flows, breaking changes, or workflow modifications
+     - Mandatory comprehensive E2E test coverage
+     - Full regression test suite required
+     - Performance benchmarking before/after
+
+   - **Medium Impact**: Data usage modifications, shared state changes, or new dependencies
+     - Integration tests minimum requirement
+     - Targeted E2E tests for affected workflows
+     - Edge case coverage mandatory
+
+   - **Low Impact**: Read-only operations, logging additions, or monitoring hooks
+     - Unit test coverage sufficient
+     - Smoke tests for integration points
+
+   **Verification Pattern**:
+   1. **Establish Baseline**
+      - Test and document existing feature behavior
+      - Capture performance metrics
+      - Record expected outputs
+
+   2. **Apply Changes**
+      - Deploy or enable new feature
+      - Maintain feature flags for rollback capability
+
+   3. **Verify Existing Features**
+      - Confirm existing features still function correctly
+      - Compare against baseline metrics
+      - Validate no unexpected side effects
+
+   4. **Measure Performance** (NOT long-term stability tests)
+      - Response times within acceptable limits (project-specific)
+      - Resource usage remains stable
+      - No memory leaks or degradation
+
+   **Success Criteria**:
+   - Zero breaking changes in existing workflows
+   - Performance degradation within project-defined acceptable limits
+   - No new errors in previously stable features
+   - All integration points maintain expected contracts
+   - Backward compatibility preserved where required
+
+   **Documentation Requirements**:
+   - Map all integration points in Design Doc
+   - Document test coverage for each impact level
+
+## Test Design Principles
+
+### Test Case Structure
+- Tests consist of three stages: **Setup, Execute, Verify** (also known as Arrange-Act-Assert or Given-When-Then)
+- Clear naming that shows purpose of each test
+- One test case verifies only one behavior
+- Test names should describe expected behavior, not implementation
+
+### Test Data Management
+- Manage test data in dedicated directories
+- Define test-specific configuration values
+- Always mock sensitive information (passwords, tokens, API keys)
+- Keep test data minimal, using only data directly related to test case verification
+
+### Test Independence
+- Each test should be able to run in isolation
+- Tests should not depend on execution order
+- Clean up test state after each test
+- Avoid shared mutable state between tests
+
+## Mock and Stub Usage Policy
+
+✅ **Recommended: Mock external dependencies in unit tests**
+- Merit: Ensures test independence and reproducibility
+- Practice: Mock databases, APIs, file systems, and other external dependencies
+- Use framework-appropriate mocking tools
+
+❌ **Avoid: Actual external connections in unit tests**
+- Reason: Slows test speed and causes environment-dependent problems
+- Exception: Integration tests that specifically test external integration
+
+### Mock Decision Criteria
+| Mock Characteristics | Response Policy |
+|---------------------|-----------------|
+| **Simple and stable** | Consolidate in common helpers |
+| **Complex or frequently changing** | Individual implementation |
+| **Duplicated in 3+ places** | Consider consolidation |
+| **Test-specific logic** | Individual implementation |
+
+## Test Granularity Principles
+
+### Core Principle: Observable Behavior Only
+**MUST Test**:
+- Public APIs and contracts
+- Return values and outputs
+- Exceptions and error conditions
+- External calls and side effects
+- Persisted state changes
+
+**MUST NOT Test**:
+- Internal implementation details not exposed publicly
+- Internal state that's not observable from outside
+- Algorithm implementation details
+- Framework/library internals
+
+### Test Failure Response Decision Criteria
+
+**Fix tests when:**
+- Expected values are wrong
+- Tests reference non-existent features
+- Tests depend on implementation details
+- Tests were written only for coverage
+
+**Fix implementation when:**
+- Tests represent valid specifications
+- Business logic requirements have changed
+- Important edge cases are failing
+
+**When in doubt**: Confirm with stakeholders or domain experts
+
+## Test Implementation Best Practices
+
+### Naming Conventions
+- Test files: Follow your language/framework conventions
+- Test suites: Names describing target features or situations
+- Test cases: Names describing expected behavior (not implementation)
+
+### Test Code Quality Rules
+
+✅ **Recommended: Keep all tests always active**
+- Merit: Guarantees test suite completeness
+- Practice: Fix problematic tests and activate them
+
+❌ **Avoid: Skipping or commenting out tests**
+- Reason: Creates test gaps and incomplete quality checks
+- Solution: Either fix the test or completely delete if truly unnecessary
+
+## Test Quality Criteria [MANDATORY]
+
+1. **Boundary coverage**: Include empty/zero/max/error cases with happy paths
+2. **Literal expectations**: Use literal values in assertions, not computed expressions
+3. **Result verification**: Assert return values and state, not call order
+4. **Meaningful assertions**: Every test must have at least one assertion
+5. **Mock external I/O only**: Mock DB/API/filesystem, use real internal utilities
+
+### Test Helper Guidelines
+
+**Basic Principles**
+Test helpers should reduce duplication and improve maintainability.
+
+**Usage Examples**
+- Builder patterns for test data creation
+- Custom assertions for domain-specific validation
+- Shared setup/teardown utilities
+- Common mock configurations
+
+## Quality Check Commands [MANDATORY for VERIFY phase]
+
+**Execute quality checks appropriate for your language and project setup:**
+
+### Required Quality Checks
+Your project MUST have mechanisms to verify:
+
+1. **All Tests Pass**
+   - Unit tests execute successfully
+   - Integration tests (if applicable) pass
+   - No test failures or errors
+
+2. **Code Builds Successfully**
+   - Compilation succeeds (for compiled languages)
+   - No build errors or warnings
+
+3. **Code Style Compliance**
+   - Linting rules are satisfied
+   - Formatting standards are met
+   - Style guide adherence verified
+
+4. **Type Safety** (for typed languages)
+   - Type checking passes
+   - No type errors or warnings
+
+### Implementation Guidelines
+- **Identify Your Tools**: Use your project's existing quality tools (test runners, linters, formatters, type checkers)
+- **Zero Error Policy**: ALL quality checks must pass with 0 errors before task completion
+- **Document Execution**: Note which quality checks were run and their results
+- **Project-Specific**: Adapt to your specific language, framework, and tooling setup
+
+### ENFORCEMENT
+- Cannot proceed with task completion if ANY quality check fails
+- Must fix all errors and warnings before marking task complete
+- If your project lacks certain quality tools, establish them or document the gap