@oleksandr.rudnychenko/sync_loop 0.2.1

package/template/.agent-loop/patterns/testing-guide.md

@@ -0,0 +1,258 @@
+# Testing Guide (R2)
+
+Comprehensive testing patterns for safe iteration and regression prevention.
+Referenced from [../patterns.md](../patterns.md).
+
+---
+
+## Test Organization
+
+```
+tests/
+├── conftest.py          # Shared fixtures, global setup
+├── factories.py         # Test data builders
+├── mocks.py             # Mock implementations for external deps
+├── api/                 # API/endpoint tests (HTTP client)
+├── integration/         # Multi-component workflow tests
+└── unit/                # Pure logic tests (no I/O)
+```
+
+---
+
+## Pattern 1: Fixture-Based Setup
+
+```python
+# Environment isolation — reset global state each test
+@pytest.fixture(autouse=True)
+def reset_context():
+    """Reset global state before each test."""
+    import app.context
+    app.context._context = None
+    yield
+    app.context._context = None
+
+# Test app configuration
+@pytest.fixture
+def test_app(monkeypatch: pytest.MonkeyPatch, tmp_path: Path):
+    """Configure app with test-safe environment."""
+    monkeypatch.setenv("APP_ENV", "testing")
+    monkeypatch.setenv("ENABLE_BACKGROUND_TASKS", "0")
+    yield create_app()
+
+# API client for endpoint tests
+@pytest.fixture
+def client(test_app):
+    return TestClient(test_app)
+```
+
+---
+
+## Pattern 2: Factory Pattern for Test Data
+
+```python
+class EntityFactory:
+    @staticmethod
+    def create(
+        id: str | None = None,
+        name: str = "Test Entity",
+        entity_type: str = "default",
+        **extras: Any,
+    ) -> dict[str, Any]:
+        return {
+            "id": id or str(uuid4()),
+            "name": name,
+            "metadata": {"type": entity_type, **extras},
+        }
+
+    @staticmethod
+    def with_full_analysis() -> dict[str, Any]:
+        """Semantic constructor for entity with all analysis fields populated."""
+        return EntityFactory.create(
+            name="Fully Analyzed Entity",
+            entity_type="analyzed",
+            score=85.0,
+            grade="B",
+        )
+```
+
+---
+
+## Pattern 3: Mock External Dependencies
+
+```python
+class MockExternalService:
+    """Mock for any external service boundary (LLM, API, storage)."""
+    def __init__(self, response: dict | str | None = None):
+        self.response = response or self._default_response()
+        self.calls: list[dict] = []
+
+    async def __call__(self, prompt: str, context: str, **kwargs):
+        self.calls.append({"prompt": prompt, "context": context})
+        return json.dumps(self.response), {}
+
+    @property
+    def call_count(self) -> int:
+        return len(self.calls)
+```
+
+Usage:
+```python
+@pytest.fixture
+def mock_service() -> MockExternalService:
+    return MockExternalService(response={"score": 85})
+
+def test_analysis_delegates_to_service(mock_service):
+    service = AnalysisService(external=mock_service)
+    result = service.analyze(...)
+    assert mock_service.call_count == 1
+```
+
+---
+
+## Pattern 4: Class-Based Test Organization
+
+```python
+class TestParseResponse:
+    def test_valid_json_response(self):
+        response = '{"entity_type": "analyzed", "score": 85}'
+        result = parse_response(response)
+        assert result.entity_type == EntityType.ANALYZED
+
+    def test_invalid_json_fallback(self):
+        result = parse_response("Not JSON")
+        assert result.entity_type == EntityType.UNKNOWN
+
+    def test_missing_fields_use_defaults(self):
+        result = parse_response('{"entity_type": "analyzed"}')
+        assert result.score == 0.0
+```
+
+---
+
+## Pattern 5: Parametrized Tests
+
+```python
+@pytest.mark.parametrize("score,expected_grade", [
+    (95, "A"), (90, "A"),
+    (89.9, "B"), (85, "B"), (80, "B"),
+    (79, "C"), (70, "C"),
+    (69, "D"), (60, "D"),
+    (59, "F"), (0, "F"),
+])
+def test_grade_thresholds(score: float, expected_grade: str):
+    assert compute_grade(score) == expected_grade
+```
+
+---
+
+## Pattern 6: Three-Layer Test Strategy
+
+```python
+# UNIT: Pure logic, no I/O
+def test_parse_response():
+    result = parse_response('{"entity_type": "analyzed"}')
+    assert result.entity_type == EntityType.ANALYZED
+
+# INTEGRATION: Multiple components, mocked external I/O
+def test_analysis_pipeline(mock_service, mock_repository):
+    service = AnalysisService(external=mock_service, repo=mock_repository)
+    report = service.analyze(entities=[...])
+    assert report.aggregate_score > 0
+
+# API: HTTP endpoint, full stack with test client
+def test_analyze_endpoint(client, mock_data):
+    response = client.post("/api/v1/analyze", json=mock_data)
+    assert response.status_code == 200
+    assert "score" in response.json()
+```
+
+---
+
+## Pattern 7: Assertion Patterns
+
+```python
+# ✅ Specific property checks
+assert report.task_id == "task-1"
+assert len(report.metrics) > 0
+assert "total_items" in [m.name for m in report.metrics]
+
+# ✅ Range/constraint checks
+assert 0 <= result.score <= 100
+assert result.entity_type in EntityType
+
+# ✅ Collection checks
+assert all(m.value >= 0 for m in report.metrics)
+assert any(r.entity_type == "analyzed" for r in results)
+
+# ❌ Vague — what is being verified?
+assert report
+assert result is not None
+```
+
+---
+
+## Pattern 8: Naming Convention
+
+Format: `test_<action>_<condition>_<outcome>`
+
+```
+test_returns_report                      # Basic happy path
+test_metrics_computed_correctly          # Specific behavior
+test_unknown_type_falls_back_to_default  # Edge case
+test_invalid_json_fallback               # Error handling
+test_missing_fields_use_defaults         # Default behavior
+test_empty_input_returns_empty_report    # Boundary condition
+```
+
+---
+
+## Test Metrics (Target)
+
+| Metric | Target |
+|--------|--------|
+| Pass Rate | 100% |
+| Unit proportion | ≥ 70% |
+| Integration proportion | ≤ 20% |
+| API proportion | ≤ 10% |
+
+---
+
+## Test Heuristics
+
+| Heuristic | Guideline |
+|-----------|-----------|
+| **Speed** | Unit < 10ms, Integration < 100ms, API < 1s |
+| **Isolation** | Each test independent, no shared mutable state |
+| **Coverage** | Critical paths and edge cases tested, not chasing 100% line coverage |
+| **Clarity** | Test name explains what behavior is being verified |
+| **Simplicity** | One logical assertion per test (multiple `assert` OK if testing one concept) |
+| **Structure** | Arrange → Act → Assert (AAA pattern) |
+| **Determinism** | No flaky tests — mock time, randomness, external systems |
+
+---
+
+## Validation Strategy
+
+1. **Changed symbols first** — run tests for files you changed
+2. **Adjacent modules second** — run tests for callers/consumers
+3. **Full suite last** — once local confidence is high, run everything
+
+```bash
+# Targeted
+pytest tests/unit/test_processor.py -x -v
+
+# Adjacent
+pytest tests/unit/ tests/integration/ -x -v -k "processor or analysis"
+
+# Full suite
+pytest tests/ -x -v
+```
+
+---
+
+## Related Documents
+
+| Document | Purpose |
+|----------|---------|
+| [../validate-env.md](../validate-env.md) | Gate orchestration (test gate details) |
+| [refactoring-workflow.md](refactoring-workflow.md) | Safe code movement (tests after each move) |

package/template/.agent-loop/patterns.md

@@ -0,0 +1,256 @@
+# Pattern Registry & Routing Index
+
+Central pattern index for GKP routing and LEARN persistence.
+Referenced from [reasoning-kernel.md](reasoning-kernel.md).
+
+---
+
+## Pattern Families
+
+| IDs | Family | Primary Spec |
+|-----|--------|--------------|
+| **P1–P11** | Core code architecture patterns | [patterns/code-patterns.md](patterns/code-patterns.md) |
+| **R1–R3** | Refactoring, testing, and API quality patterns | [patterns/refactoring-workflow.md](patterns/refactoring-workflow.md), [patterns/testing-guide.md](patterns/testing-guide.md), [patterns/api-standards.md](patterns/api-standards.md) |
+
+---
+
+## Architecture Baseline
+
+```
+Routes → Services → Repositories → Libs
+```
+
+{Replace with actual project layers during bootstrap.}
+
+### Layer Intent
+- **Routes**: Transport/boundary only. No business logic.
+- **Services**: Business orchestration. Domain logic lives here.
+- **Repositories**: Data access contracts.
+- **Libs**: Infrastructure utilities. No imports from app modules.
+
+### Non-Bypass Rules
+- Never import across incompatible layers
+- Never bypass the service layer from transport handlers
+- Never change public APIs without explicit approval
+
+{Add project-specific non-bypass rules here.}
+
+---
+
+## Core Code Patterns (P1–P11)
+
+> Full spec with examples → [patterns/code-patterns.md](patterns/code-patterns.md)
+
+#### P1 · Port/Adapter
+
+Infrastructure abstraction via interface protocols (ports) with concrete implementations (adapters).
+
+**Use when:** Adding external service · Swapping infrastructure impl · Writing tests that mock I/O · Reviewing layer boundary compliance · Creating a new infrastructure package
+
+#### P2 · Domain Module
+
+Standard multi-file layout for each business domain. Enforces separation of concerns within features.
+
+**Use when:** Creating a new feature module · Adding a file to existing module · Checking module completeness · Reviewing cross-module dependencies · Moving logic out of routes into services
+
+#### P3 · Background Task Boundary
+
+Async background processing with runtime dependency injection. Task handlers stay thin; business logic lives in services.
+
+**Use when:** Adding a background processing task · Debugging task dependency injection · Understanding task status tracking · Reviewing task error handling and retry logic
+
+#### P4 · App Context / Composition Root
+
+Global dependency container initialized once at startup. Provides config, session factory, and shared services.
+
+**Use when:** Understanding runtime dependency wiring · Adding a new global dependency · Debugging initialization errors · Writing test fixtures that reset global state
+
+#### P5 · Transport Route
+
+Boundary endpoints using dependency injection for service access. Routes contain only transport concerns.
+
+**Use when:** Adding a new endpoint · Wiring a service into a route · Reviewing route-to-service boundary · Adding request/response validation
+
+#### P6 · Typed Models
+
+Domain entities with explicit types, default factories for collections, and serialization methods.
+
+**Use when:** Defining a new entity or value object · Adding fields to existing model · Reviewing serialization behavior · Deciding model type (dataclass vs schema model)
+
+#### P7 · Collection/Enum Safety
+
+Type-safe namespace references replacing magic strings with enums/constants.
+
+**Use when:** Adding a new namespace/collection · Debugging name mismatches · Reviewing normalization logic
+
+#### P8 · Error Handling
+
+Layered exception hierarchy: domain base → specific errors. Routes catch domain errors and map to transport status codes.
+
+**Use when:** Adding error handling · Defining domain exceptions · Mapping service errors to transport responses · Reviewing error propagation across layers
+
+#### P9 · Type Hints Everywhere
+
+All functions require complete type annotations: parameters, returns, generics. No bare `Any` without justification.
+
+**Use when:** Writing any new function · Fixing type checker errors · Reviewing type completeness · Using project-specific type aliases
+
+#### P10 · Service Orchestration
+
+Services accept all dependencies via constructor. No hidden imports or global access in service methods.
+
+**Use when:** Creating a new service · Making a service testable · Wiring mocks in test fixtures · Reviewing service constructor signatures
+
+#### P11 · Config Isolation
+
+Environment-based config with centralized source and startup validation.
+
+**Use when:** Adding environment variable · Understanding config overrides · Debugging config initialization
+
+---
+
+## Process Patterns (R1–R3)
+
+#### R1 · Refactoring Workflow
+
+4-phase checklist for safe file moves, import changes, and module restructuring.
+
+**Use when:** Moving a file · Renaming a module · Splitting a large file · Merging modules · Running post-refactor validation
+
+**Spec:** [patterns/refactoring-workflow.md](patterns/refactoring-workflow.md)
+
+#### R2 · Testing Guide
+
+Test patterns covering the full test pyramid with fixtures, factories, mocks, and parameterized tests.
+
+**Use when:** Writing a new test · Setting up fixtures · Creating mock adapters · Deciding test layer · Reviewing naming conventions · Structuring parameterized tests
+
+**Spec:** [patterns/testing-guide.md](patterns/testing-guide.md)
+
+#### R3 · API / Boundary Standards
+
+Documentation and contract requirements for boundary endpoints: typed models, docstrings, schema generation.
+
+**Use when:** Adding a new endpoint · Documenting existing routes · Reviewing response models · Generating or updating specs
+
+**Spec:** [patterns/api-standards.md](patterns/api-standards.md)
+
+---
+
+## GKP Routing Table
+
+| If task involves… | Use IDs | Read this first |
+|-------------------|---------|-----------------|
+| Ports/adapters and layering | P1, P2, P10 | [patterns/code-patterns.md](patterns/code-patterns.md) |
+| Task orchestration/runtime composition | P3, P4 | [patterns/code-patterns.md](patterns/code-patterns.md) |
+| Boundary contracts and typing | P5, P6, P9 | [patterns/code-patterns.md](patterns/code-patterns.md) |
+| Error policies and config safety | P8, P11 | [patterns/code-patterns.md](patterns/code-patterns.md) |
+| File moves and API-safe refactors | R1 | [patterns/refactoring-workflow.md](patterns/refactoring-workflow.md) |
+| Verification strategy | R2 | [patterns/testing-guide.md](patterns/testing-guide.md) |
+| Interface docs/schema discipline | R3 | [patterns/api-standards.md](patterns/api-standards.md) |
+
+---
+
+## Artifact Placement
+
+### Application Code
+
+| Artifact Type | Location |
+|---------------|----------|
+| Domain models | `{modules}/{domain}/models.*` |
+| Business services | `{modules}/{domain}/services.*` |
+| Transport routes | `{modules}/{domain}/routes.*` |
+| Infrastructure ports | `{libs}/{component}/port.*` |
+| Infrastructure adapters | `{libs}/{component}/{impl}.*` |
+| Utilities | `{libs}/utils/` |
+
+### Tests
+
+| Test Type | Location | Purpose |
+|-----------|----------|---------|
+| Unit | `tests/unit/test_{component}.*` | Pure logic, no I/O |
+| Integration | `tests/integration/test_{feature}.*` | Multi-component workflows |
+| API/Endpoint | `tests/api/test_{endpoint}.*` | Transport endpoint tests |
+| Fixtures | `tests/conftest.*` | Shared test fixtures |
+| Factories | `tests/factories.*` | Test data builders |
+| Mocks | `tests/mocks.*` | Mock adapters |
+
+### Documentation & Agent Loop
+
+| Doc Type | Location |
+|----------|----------|
+| Architecture overview | `docs/ARCHITECTURE.md` |
+| Engineering reports | `docs/reports/YYYY-MM-DD-*.md` |
+| Report artifacts | `docs/reports/artifacts/` |
+| Pattern index + learned fixes | `.agent-loop/patterns.md` |
+| Pattern detail specs | `.agent-loop/patterns/*.md` |
+| Domain terminology | `.agent-loop/glossary.md` |
+
+---
+
+## Naming Anti-Patterns
+
+| Anti-Pattern | Correct Approach | Reason |
+|--------------|------------------|--------|
+| `*_v1.py`, `*_v2.py` | Update existing or rename clearly | Git handles versions |
+| `*_new.py`, `*_old.py` | Refactor into `*_next.py` then swap | "New" becomes old quickly |
+| `test_*_v2.py` | `test_<original_name>.py` | 1:1 mapping to source module |
+
+---
+
+## Learned Patterns (LEARN writes here)
+
+### Auto-Fixes
+
+| Trigger | Root Cause | Minimal Safe Fix | Auto-Apply |
+|---------|------------|------------------|------------|
+| Missing explicit return type | Signature drift | Add concrete return annotation | ✅ |
+| Stray debug artifact | Temporary local instrumentation left in patch | Remove or replace with standard logging | ✅ |
+| Caller mismatch after rename | Incomplete refactor propagation | Update all known call sites before merge | ⚠️ |
+
+### Common Errors
+
+| Symptom | Why It Happens | Prevention Heuristic |
+|---------|----------------|----------------------|
+| Gate keeps failing with small patch changes | Symptoms fixed, not root cause | Patch the first cause in dependency chain |
+| Neighbor break after “safe” refactor | Consumer map incomplete | Run validate-n immediately after structural edits |
+| Quality regressions in fast fixes | No targeted test sequence | Start with narrow tests, then expand |
+
+### Heuristics
+
+| Do More | Do Less |
+|---------|---------|
+| Compress context into explicit constraints | Carry large raw snippets forward |
+| Validate boundaries early | Delay compatibility checks |
+| Keep patches reversible | Mix refactor and feature changes together |
+
+### Pruning Records
+
+Populated by [feedback.md §Branch Pruning Protocol](feedback.md) during the LEARN phase when a failed approach is pruned.
+
+| Attempt | Strategy | Failure Reason | Constraint Added |
+|---------|----------|----------------|------------------|
+| — | — | — | — |
+
+---
+
+## Pattern Addition Policy
+
+Add a new pattern when all are true:
+1. The approach is reusable across multiple tasks
+2. It reduces failure recurrence
+3. It has clear constraints and examples
+
+Write location:
+- Short rule: table in this file
+- Deep implementation: dedicated section/file under `patterns/`
+
+---
+
+## Related Documents
+
+| Document | Purpose |
+|----------|---------|
+| [reasoning-kernel.md](reasoning-kernel.md) | End-to-end protocol and mode selection |
+| [feedback.md](feedback.md) | Failure-to-learning bridge |
+| [glossary.md](glossary.md) | Canonical naming and ambiguity resolution |