@oleksandr.rudnychenko/sync_loop 0.2.1

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

@@ -0,0 +1,113 @@
+# Domain Glossary
+
+Canonical terminology for the project codebase. All code, comments, docs, and agent reasoning must use these terms.
+Referenced from [patterns.md](patterns.md). Cross-references use `[→ ID]` pattern IDs from the registry.
+
+**Use when:**
+- Naming a new variable, field, class, or parameter
+- Writing comments, docstrings, or documentation
+- Interpreting domain concepts in user requests or specs
+- Resolving ambiguity between similar terms
+- Checking deprecated aliases before using a term in new code
+
+---
+
+## Architecture Terms
+
+{Fill in during bootstrap with project-specific layer terms.}
+
+| Term | Canonical Symbol | Definition |
+|------|------------------|------------|
+| **service** | `*Service` [→ P2, P10] | Business orchestration unit — contains domain logic and data access. No transport concerns. |
+| **route** | `*_router` / `*_controller` [→ P5] | Transport boundary — handles requests, delegates to services. No business logic. |
+| **adapter** | `*Adapter` [→ P1] | Concrete implementation of an infrastructure port/interface. |
+| **config** | `Settings` / `Config` [→ P11] | Centralized configuration — single env source with startup validation. |
+
+{Add project-specific architecture terms here.}
+
+---
+
+## Domain Objects
+
+{Fill in during bootstrap with actual domain models.}
+
+| Term | Canonical Symbol | Model / Location | Description |
+|------|------------------|------------------|-------------|
+| {entity} | `{ClassName}` | `{models/file.py}` | {what it represents} |
+
+---
+
+## Agent Loop Lifecycle Terms
+
+| Term | Meaning |
+|------|---------|
+| **SENSE** | State detection and requirement extraction |
+| **GKP** | Generated Knowledge Pack — context retrieval + compression |
+| **DECIDE+ACT** | Mode selection and immediate implementation |
+| **CHALLENGE-TEST** | Validation loop with retry-driven patching |
+| **UPDATE** | State transition persistence |
+| **LEARN** | Persisting reusable corrections and heuristics |
+| **REPORT** | Writing non-trivial session outcomes |
+
+---
+
+## Naming Rules
+
+1. **One concept → one canonical term** — never use synonyms in code
+2. **Prefer explicit nouns** over abbreviations (`service` not `svc`)
+3. **Keep boundary model names stable** once published to consumers
+4. **Record deprecated aliases** before removal (see table below)
+5. **Suffix conventions** (adapt to project):
+   - `*Service` for business logic
+   - `*Router` / `*Controller` for transport handlers
+   - `*Adapter` for infrastructure implementations
+   - `*Port` / `*Interface` for infrastructure abstractions
+
+---
+
+## Deprecated Alias Table
+
+| Deprecated | Canonical | Notes |
+|------------|-----------|-------|
+| `svc` | `service` | Abbreviated form |
+| `handler` | `service` | Avoid ambiguity with route handlers |
+
+{Add project-specific deprecated aliases here.}
+
+---
+
+## Data Flow Diagram
+
+{Fill in during bootstrap with actual project data flow.}
+
+```
+┌──────────────────────────────┐
+│        USER INPUT            │
+├──────────────────────────────┤
+│  Request → Transport Layer   │
+└─────────────┬────────────────┘
+              │
+              ▼
+┌──────────────────────────────┐
+│       SERVICE LAYER          │
+├──────────────────────────────┤
+│  Business Logic → Data Access│
+└─────────────┬────────────────┘
+              │
+              ▼
+┌──────────────────────────────┐
+│         OUTPUT               │
+├──────────────────────────────┤
+│  Response → Side Effects     │
+└──────────────────────────────┘
+```
+
+---
+
+## Related Documents
+
+| Document | Purpose |
+|----------|---------|
+| [reasoning-kernel.md](reasoning-kernel.md) | Where lifecycle terms are executed |
+| [patterns.md](patterns.md) | Where pattern IDs are defined and routed |
+| [../AGENTS.md](../AGENTS.md) | Main entrypoint with full architecture reference |

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

@@ -0,0 +1,132 @@
+# API Standards (R3)
+
+Standards for consistent boundary contracts: HTTP routes, request/response models, error envelopes, and documentation.
+Referenced from [../patterns.md](../patterns.md).
+
+---
+
+## Requirements
+
+1. **Typed Models**: Every route must define explicit request and response models. No raw `dict` or untyped `JSONResponse` for success cases.
+
+2. **Docstrings**: Every route handler must have a docstring with summary and description.
+
+3. **Tags & Metadata**: Group routes with semantic tags. Provide `summary` / `description` in path operations.
+
+4. **Spec Generation**: After modifying routes, regenerate API documentation (OpenAPI spec, Swagger, or equivalent).
+
+---
+
+## Workflow for New Routes
+
+```
+1. Define Request/Response models in the module's models file
+2. Implement the route handler using those models
+3. Register the router in the app entrypoint with appropriate tags
+4. Run spec generation script
+5. Verify generated docs match expectations
+```
+
+### Example Route
+
+```python
+# models.py — typed boundary contracts
+@dataclass
+class CreateEntityRequest:
+    name: str
+    entity_type: str
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+@dataclass
+class EntityResponse:
+    id: str
+    name: str
+    entity_type: str
+    status: str
+    created_at: str
+
+# routes.py — thin transport layer
+@router.post("/entities", response_model=EntityResponse)
+def create_entity(
+    data: CreateEntityRequest,
+    service: EntityService = Depends(get_service),
+) -> EntityResponse:
+    """Create a new entity for processing.
+
+    Validates input, delegates to service, returns created entity.
+    """
+    result = service.create(data)
+    return EntityResponse(
+        id=result.id,
+        name=result.name,
+        entity_type=result.entity_type,
+        status=result.status,
+        created_at=result.created_at.isoformat(),
+    )
+```
+
+---
+
+## Error Envelope
+
+All error responses must follow a consistent structure:
+
+```python
+# Standard error response
+@dataclass
+class ErrorResponse:
+    error: str          # Machine-readable error code
+    message: str        # Human-readable description
+    details: dict = field(default_factory=dict)  # Optional context
+
+# Usage at route boundary
+@router.get("/entities/{entity_id}")
+def get_entity(entity_id: str, service = Depends(get_service)):
+    try:
+        return service.get(entity_id)
+    except NotFoundError as exc:
+        raise HTTPException(status_code=404, detail=str(exc))
+    except ValidationError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+```
+
+---
+
+## Documentation Rules
+
+| Rule | Detail |
+|------|--------|
+| Document each endpoint intent | What does it do, who calls it |
+| Define validation constraints | Required fields, ranges, formats |
+| Include success + error examples | Show typical 200, 400, 404, 500 |
+| Keep schema docs in sync | Regenerate after every route change |
+
+---
+
+## Change Safety
+
+| Change Type | Requirements |
+|-------------|-------------|
+| **Additive** (new field, new endpoint) | Must be backward-compatible; new fields optional with defaults |
+| **Modification** (rename field, change type) | Requires migration notes + caller updates + NEIGHBOR validation |
+| **Removal** (delete field, remove endpoint) | Requires deprecation period, caller audit, explicit approval |
+
+---
+
+## Versioning Strategy
+
+- Prefer additive changes over breaking changes
+- When breaking changes are unavoidable:
+  1. Document the change in migration notes
+  2. Update all known consumers
+  3. Run NEIGHBOR validation to check boundary contracts
+  4. Consider a version prefix if multiple consumers exist
+
+---
+
+## Related Documents
+
+| Document | Purpose |
+|----------|---------|
+| [../validate-n.md](../validate-n.md) | Contract compatibility checks (NEIGHBOR) |
+| [code-patterns.md](code-patterns.md) | P5 (Transport Route), P6 (Typed Models) |

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

@@ -0,0 +1,300 @@
+# Code Patterns (P1–P11)
+
+Reusable implementation patterns for layered application code.
+Referenced from [../patterns.md](../patterns.md).
+
+---
+
+## P1 · Port/Adapter
+
+Abstracts infrastructure behind protocol interfaces. Decouples domain logic from external systems.
+
+```python
+# Port (interface/protocol)
+class StoragePort(Protocol):
+    def search(
+        self,
+        collection: str,
+        query: str,
+        *,
+        filters: dict | None = None,
+        limit: int = 10,
+    ) -> list[Record]: ...
+
+# Adapter (concrete implementation)
+class DatabaseAdapter:
+    def __init__(self, client: DBClient) -> None:
+        self._client = client
+
+    def search(
+        self,
+        collection: str,
+        query: str,
+        *,
+        filters: dict | None = None,
+        limit: int = 10,
+    ) -> list[Record]:
+        # Implementation against real infrastructure
+        ...
+```
+
+**Key rules:**
+- Port lives in `libs/{component}/port.*`
+- Adapter lives in `libs/{component}/{impl}.*`
+- Services depend on port interfaces, not adapters directly
+
+---
+
+## P2 · Domain Module
+
+Each domain module follows a consistent multi-file layout:
+
+| File | Purpose |
+|------|---------|
+| `models.*` | Domain entities and value objects |
+| `services.*` | Business logic and orchestration |
+| `routes.*` | Transport endpoints |
+| `tasks.*` | Background tasks (if async processing needed) |
+
+```python
+# services.py — business logic only, no transport concerns
+class OrderService:
+    def __init__(self, repository: OrderRepository) -> None:
+        self._repository = repository
+
+    def process(self, *, order_id: str) -> ProcessResult:
+        order = self._repository.get(order_id)
+        # business logic here
+        return ProcessResult(order_id=order.id, status="completed")
+```
+
+---
+
+## P3 · Background Task Boundary
+
+Task handlers stay thin. Business logic always lives in services.
+
+```python
+# tasks.py — thin wrapper, delegates to service
+def process_order_task(runtime: TaskRuntime, order_id: str):
+    """Background task that delegates to service."""
+    service = runtime.order_service
+    service.update_status(order_id, status="processing")
+
+    try:
+        service.process(order_id=order_id)
+        service.update_status(order_id, status="completed")
+    except Exception as exc:
+        service.update_status(order_id, status="failed", error=str(exc))
+        raise
+```
+
+**Key rules:**
+- Tasks never contain business logic
+- Dependencies injected via runtime, not imported directly
+- Always update status on success and failure
+
+---
+
+## P4 · App Context / Composition Root
+
+Centralized dependency wiring, initialized once at startup:
+
+```python
+@dataclass
+class AppContext:
+    config: Config
+    session_factory: SessionFactory
+    services: ServiceRegistry
+    logger: Logger
+
+_context: AppContext | None = None
+
+def init_app_context(config: Config) -> AppContext:
+    global _context
+    if _context:
+        return _context
+    _context = AppContext(config=config, ...)
+    return _context
+
+def get_app_context() -> AppContext:
+    if _context is None:
+        return init_app_context(load_config())
+    return _context
+```
+
+---
+
+## P5 · Transport Route
+
+Routes only handle transport concerns; all logic delegated to services:
+
+```python
+router = APIRouter()
+
+def get_service() -> OrderService:
+    ctx = get_app_context()
+    return OrderService(ctx.repository)
+
+@router.post("/orders")
+def create_order(
+    data: CreateOrderRequest,
+    service: OrderService = Depends(get_service),
+) -> OrderResponse:
+    result = service.create(data)
+    return OrderResponse(id=result.id, status=result.status)
+```
+
+---
+
+## P6 · Typed Models
+
+Domain entities with explicit types and serialization:
+
+```python
+@dataclass(slots=True)
+class OrderItem:
+    product_id: str
+    quantity: int
+    unit_price: float
+    tags: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "product_id": self.product_id,
+            "quantity": self.quantity,
+            "unit_price": self.unit_price,
+            "tags": self.tags,
+        }
+```
+
+---
+
+## P7 · Collection/Enum Safety
+
+Replace magic strings with typed enums:
+
+```python
+class Collection(str, Enum):
+    ORDERS = "orders"
+    PRODUCTS = "products"
+    USERS = "users"
+
+# Usage: repository.query(Collection.ORDERS, ...)
+# NOT: repository.query("orders", ...)
+```
+
+---
+
+## P8 · Error Handling
+
+Layered exception hierarchy with boundary translation:
+
+```python
+# Domain exceptions
+class DomainError(Exception):
+    """Base error for domain."""
+
+class NotFoundError(DomainError):
+    """Resource not found."""
+
+class ValidationError(DomainError):
+    """Invalid input or state."""
+
+# Route-level translation
+@router.get("/orders/{order_id}")
+def get_order(order_id: str, service = Depends(get_service)):
+    try:
+        return service.get(order_id)
+    except NotFoundError as exc:
+        raise HTTPException(status_code=404, detail=str(exc))
+    except ValidationError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+```
+
+---
+
+## P9 · Type Hints Everywhere
+
+All code must have complete type annotations:
+
+```python
+# ✅ Good — fully typed
+def process(
+    order_id: str,
+    *,
+    callback: Callable[..., Awaitable[Response]] | None = None,
+) -> tuple[str, dict[str, Any]] | None:
+    ...
+
+# ❌ Bad — missing annotations
+def process(order_id, callback=None):
+    ...
+```
+
+**Common type aliases:**
+```python
+SessionFactory = Callable[[], Session]
+Filters = Mapping[str, Any]
+```
+
+---
+
+## P10 · Service Orchestration
+
+Services accept all dependencies via constructor — no hidden state:
+
+```python
+# Production code
+class AnalysisService:
+    def __init__(
+        self,
+        repository: Repository,
+        evaluator: EvaluationService,
+    ):
+        self._repository = repository
+        self._evaluator = evaluator
+
+# Test code — inject mocks
+service = AnalysisService(
+    repository=mock_repository,
+    evaluator=mock_evaluator,
+)
+```
+
+---
+
+## P11 · Config Isolation
+
+Centralized, environment-based configuration with startup validation:
+
+```python
+@dataclass
+class Config:
+    database_url: str
+    debug: bool = False
+    max_workers: int = 4
+
+    @classmethod
+    def from_env(cls) -> "Config":
+        return cls(
+            database_url=os.environ["DATABASE_URL"],
+            debug=os.environ.get("DEBUG", "0") == "1",
+            max_workers=int(os.environ.get("MAX_WORKERS", "4")),
+        )
+```
+
+**Key rules:**
+- All config read from environment at startup
+- No scattered `os.environ` calls inside business logic
+- Test config overrides controlled via fixtures
+
+---
+
+## Related Documents
+
+| Document | Purpose |
+|----------|---------|
+| [../patterns.md](../patterns.md) | Pattern routing index |
+| [refactoring-workflow.md](refactoring-workflow.md) | Safe structural changes |
+| [testing-guide.md](testing-guide.md) | Verification strategy |

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

@@ -0,0 +1,114 @@
+# Refactoring Workflow (R1)
+
+Checklist and approach for moving files, changing imports, or restructuring modules.
+Referenced from [../patterns.md](../patterns.md).
+
+---
+
+## Refactoring Checklist
+
+```
+Phase 1: PLAN
+  ☐ Identify all files to move/rename/extract
+  ☐ Map old imports → new imports
+  ☐ Check for documentation references (README, docstrings, agent-loop specs)
+  ☐ Identify public interfaces that must remain stable
+
+Phase 2: EXECUTE
+  ☐ Move files
+  ☐ Update imports in moved files (internal references)
+  ☐ Update all caller imports (use grep to find every reference)
+  ☐ Update documentation examples if they contain import paths
+  ☐ Update .agent-loop/patterns.md structure section if layout changed
+
+Phase 3: VALIDATE (NON-NEGOTIABLE)
+  ☐ 1. Type check: run project type checker
+  ☐ 2. Run tests: execute test suite with fail-fast
+  ☐ 3. Check docs: grep for old import paths across all files
+  ☐ 4. Verify no orphaned imports (unused or broken)
+
+Phase 4: DOCUMENT
+  ☐ Update README structure section
+  ☐ Update architecture docs if needed
+  ☐ Create report in docs/reports/ if the refactor is major
+```
+
+---
+
+## Example: Moving a Module File
+
+```bash
+# 1. Move file
+mv src/modules/old_location/processor.py src/modules/new_location/processor.py
+
+# 2. Update imports inside the moved file (internal references)
+# e.g., relative imports that changed due to new directory depth
+
+# 3. Find ALL references to the old path
+grep -r "from src.modules.old_location.processor" .
+grep -r "import old_location.processor" .
+
+# 4. Update each reference found:
+#    - tests/unit/test_processor.py
+#    - src/modules/new_location/tasks.py
+#    - docs/architecture.md (if it mentions import paths)
+
+# 5. MANDATORY: Run validation
+# Type check → Tests → Grep for leftover old paths
+```
+
+**Why tests after docs?** Documentation often contains import examples. Tests verify imports actually work and catch typos in updated paths.
+
+---
+
+## Example: Extracting a Function to a New Module
+
+```bash
+# 1. Create the new module
+touch src/libs/parsing/helpers.py
+
+# 2. Move the function definition to the new file
+# Update its internal imports
+
+# 3. In the original file, replace the function body with an import:
+#    from src.libs.parsing.helpers import parse_response
+
+# 4. Find all OTHER callers of the original location
+grep -r "from src.modules.analysis.utils import parse_response" .
+
+# 5. Update all callers to use the new import path
+
+# 6. VALIDATE: type check + tests + grep for old path
+```
+
+---
+
+## Guardrails
+
+- **Prefer reversible steps** — move one file at a time, validate, then move next
+- **Never combine unrelated refactors** — one logical change per commit
+- **Do not hide breaking API changes** — if a public interface moved, update all consumers
+- **Never skip Phase 3** — validation is non-negotiable, even for "simple" moves
+- **Grep is your friend** — always search for the old path after moving; IDEs miss things
+
+---
+
+## Common Pitfalls
+
+| Pitfall | Prevention |
+|---------|------------|
+| Circular imports after move | Map dependency graph before moving |
+| Tests pass but type checker fails | Always run type checker first |
+| Docs reference old paths | Grep docs/ and *.md files explicitly |
+| Forgot to update __init__.py re-exports | Check all `__init__.py` files in affected packages |
+| Moved too many files at once | Move one file → validate → repeat |
+
+---
+
+## Related Documents
+
+| Document | Purpose |
+|----------|---------|
+| [../validate-env.md](../validate-env.md) | Stage 1 gates (type check, tests) |
+| [../validate-n.md](../validate-n.md) | Stage 2 neighbor checks (boundary impact) |
+| [testing-guide.md](testing-guide.md) | Regression test strategy |