@oleksandr.rudnychenko/sync_loop 0.3.2 → 0.3.3

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

@@ -7,55 +7,39 @@ 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
-```
+**Phase 1: PLAN**
+- Identify all files to move, rename, or extract
+- Map old imports to new imports
+- Check for documentation references (README, docstrings, agent-loop specs)
+- Identify public interfaces that must remain stable
+
+**Phase 2: EXECUTE**
+- Move files to their new locations
+- Update imports in moved files (internal relative references)
+- Update all caller imports (search the entire codebase for 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 the project type checker
+2. Run tests: execute the test suite with fail-fast
+3. Check docs: search 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
-```
+1. Move the file from its old location to the new location
+2. Update imports inside the moved file (relative references that changed due to new directory depth)
+3. Search the entire codebase for all references to the old path — tests, other modules, and documentation
+4. Update each reference found to point to the new path
+5. Run the mandatory validation: type check → tests → search for leftover old paths
 
 **Why tests after docs?** Documentation often contains import examples. Tests verify imports actually work and catch typos in updated paths.
 
@@ -63,23 +47,12 @@ grep -r "import old_location.processor" .
 
 ## 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
-```
+1. Create the new module file
+2. Move the function definition to the new file and update its internal imports
+3. In the original file, replace the function body with a re-export from the new location
+4. Search for all other callers of the function at the original location
+5. Update all callers to use the new import path
+6. Run the mandatory validation: type check → tests → search for old path
 
 ---
 

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

@@ -7,187 +7,84 @@ 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)
-```
+Organize tests into a top-level `tests/` directory with clear separation:
+
+| Directory | Purpose |
+|-----------|---------|
+| `tests/conftest` or `tests/helpers` | Shared fixtures, global setup |
+| `tests/factories` | Test data builders |
+| `tests/mocks` | Mock implementations for external dependencies |
+| `tests/api/` | API/endpoint tests (HTTP client) |
+| `tests/integration/` | Multi-component workflow tests |
+| `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)
-```
+Define reusable **fixtures** (setup/teardown helpers) that isolate test state:
+
+- **Environment isolation fixture**: resets any module-level singletons or global state before and after each test. Ensures one test cannot leak state into another.
+- **Test app fixture**: configures the application with test-safe environment variables (e.g., test database URL, disabled background tasks) and yields a configured app instance.
+- **Client fixture**: wraps the test app in an HTTP test client for endpoint-level tests.
+
+Each fixture is scoped to the narrowest lifecycle needed — per-test for state resets, per-session for expensive resources like database connections.
 
 ---
 
 ## 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",
-        )
-```
+Create a **factory class** (or set of builder functions) that produces valid test entities with sensible defaults. Each factory method accepts optional overrides via keyword arguments so tests only specify the fields relevant to the scenario.
+
+Provide **semantic constructors** — named factory methods like `with_full_analysis()` or `as_admin_user()` — that configure the entity for a specific test scenario. This makes test setup self-documenting and avoids duplicated setup logic across test files.
 
 ---
 
 ## 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
-```
+Define a **mock class** for each external boundary (LLM, HTTP API, storage backend, message queue). The mock:
 
----
+- Accepts a configurable response via its constructor
+- Records every call (arguments, timestamps) in an internal list
+- Returns the configured response on each invocation
+- Exposes a `call_count` property for verification
 
-## Pattern 4: Class-Based Test Organization
+Tests inject the mock via fixture, replacing the real dependency. After the test action, assertions verify both the result and the mock's call history.
 
-```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
+## Pattern 4: Class-Based Test Organization
 
-    def test_missing_fields_use_defaults(self):
-        result = parse_response('{"entity_type": "analyzed"}')
-        assert result.score == 0.0
-```
+Group related test cases into a **test class** named after the unit under test (e.g., `TestParseResponse`, `TestOrderService`). Each method within the class tests one behavior: happy path, error path, edge case, or default behavior. The class name provides namespace grouping in test runner output.
 
 ---
 
 ## 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
-```
+Use the test framework's **parametrize** mechanism to run one test function across multiple input/output pairs. Define the parameter sets as a list of tuples — each tuple contains the input values and the expected outcome. This eliminates repetitive test methods for boundary-value or threshold logic.
 
 ---
 
 ## 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()
-```
+Structure tests into three layers with distinct characteristics:
+
+- **Unit tests**: Pure logic, no I/O, no external dependencies. Test a single function or class method in isolation. Fast (< 10ms each).
+- **Integration tests**: Multiple components wired together, external I/O mocked at the boundary. Test that services, repositories, and adapters compose correctly.
+- **API tests**: Full HTTP request/response cycle through a test client. Verify status codes, response shapes, and error envelopes.
 
 ---
 
 ## 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]
+Write assertions that verify **specific properties**, not just truthiness:
 
-# ✅ Range/constraint checks
-assert 0 <= result.score <= 100
-assert result.entity_type in EntityType
+- Check exact field values on result objects
+- Verify collection lengths and membership
+- Use range/constraint assertions (value within expected bounds, enum membership)
+- Assert on collection-wide properties (all items satisfy a predicate, at least one item matches)
 
-# ✅ 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
-```
+Avoid vague assertions like "result is not None" or bare truthiness checks — they pass on wrong data.
 
 ---
 
@@ -195,14 +92,13 @@ assert result is not None
 
 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
-```
+Examples:
+- `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
 
 ---
 
@@ -237,16 +133,7 @@ test_empty_input_returns_empty_report    # Boundary condition
 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
-```
+Use the project's test runner with verbose and fail-fast flags. Filter by keyword or path to target specific modules during iterative development.
 
 ---
 

package/src/template/.agent-loop/reasoning-kernel.md

@@ -312,20 +312,39 @@ LEARN:
 
 ### 7. REPORT (Session Log)
 
-After completing a non-trivial task, persist a session summary to `docs/reports/`.
+The REPORT stage produces exactly one of three outcomes: a **report**, a **backlog task**, or **nothing**.
+Apply the decision tree below — follow it top to bottom, take the first matching branch.
 
-**When to write a report:**
+#### Decision Tree: Report vs Backlog vs Skip
 
-| Condition | Report Required | Format |
-|-----------|----------------|--------|
-| Multi-file refactoring | Yes | Full report |
-| New feature / module added | Yes | Full report |
-| Bug fix with root cause analysis | Yes | Abbreviated (scope + fix + verification) |
-| Architecture or pattern change | Yes | Full report + patterns.md update |
-| Single-file cosmetic fix | No | — |
-| Documentation-only update | No | — |
+```
+Was work implemented and committed this session?
+│
+├─ YES → Did the work touch multiple files or change architecture/patterns?
+│         │
+│         ├─ YES → Write REPORT to docs/reports/
+│         │        (multi-file refactor, new feature, root-cause fix,
+│         │         architecture change, pattern change)
+│         │
+│         └─ NO  → SKIP (single-file edit, cosmetic fix, docs-only update)
+│
+└─ NO  → Was an investigation or plan produced without implementation?
+          │
+          ├─ YES → Write BACKLOG TASK to docs/backlog/
+          │        (needs approval, complex decomposition required,
+          │         lower priority than current sprint, blocked on dependency)
+          │
+          └─ NO  → SKIP (question answered, context gathered, trivial lookup)
+```
+
+**Key distinction:** Reports document **completed work**. Backlog tasks document **planned but unexecuted work**.
+Never create both for the same task. If you implemented the work, write a report. If you only planned it, write a backlog task.
+
+#### Report: Completed Work
+
+**Trigger:** Implementation was done this session AND touched ≥2 files or changed architecture/patterns.
 
-**Report structure:**
+**Structure:**
 
 ```markdown
 # {Short Description}
@@ -355,10 +374,44 @@ After completing a non-trivial task, persist a session summary to `docs/reports/
 {What was persisted to patterns.md / patterns/ specs / glossary}
 ```
 
-**File placement:**
-- Report: `docs/reports/YYYY-MM-DD-{short-description}.md`
-- Supporting artifacts: `docs/reports/artifacts/`
+**File:** `docs/reports/YYYY-MM-DD-{slug}.md`
+**Artifacts:** `docs/reports/artifacts/`
+
+#### Backlog Task: Planned but Deferred Work
+
+**Trigger:** Investigation or planning was done this session BUT implementation was NOT executed.
+Reasons to defer: needs approval, requires decomposition, lower priority, blocked on external dependency.
+
+**Structure:**
+
+```markdown
+# {Task Title}
+
+**Date:** YYYY-MM-DD
+**Priority:** P0–P3
+**State:** planned
+
+## Context
+{Why this task exists — what was investigated, what triggered it}
+
+## Action Plan
+{Step-by-step implementation plan with file paths and scope}
+
+## Acceptance Criteria
+{Concrete conditions that define "done" — gate results, test coverage, behavior}
+
+## Dependencies
+{What must be resolved before this can start — other tasks, approvals, external}
+```
+
+**File:** `docs/backlog/YYYY-MM-DD-{slug}.md`
+**Index:** After creating the task file, add a row to `docs/backlog/index.md` with task number, title, priority (P0–P3), state (`planned`), date, and filename.
+
+#### Common Rules
+
 - Naming: date-prefixed, lowercase-kebab-case, no `_v1`/`_new` suffixes
+- Never create both a report and a backlog task for the same piece of work
+- If a backlog task is later implemented, mark it `done` in the index and write a report for the implementation session
 
 ---
 
@@ -460,7 +513,7 @@ LEARN
 [one-line do-more/do-less heuristic]
 
 REPORT (if non-trivial)
-[docs/reports/YYYY-MM-DD-{slug}.md created — or "skipped (trivial)"]
+[docs/reports/YYYY-MM-DD-{slug}.md | docs/backlog/YYYY-MM-DD-{slug}.md — or "skipped (trivial)"]
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 

package/src/template/.agent-loop/validate-n.md

@@ -53,51 +53,15 @@ When modifying any of these, check all neighbors in the coupling path.
 
 ### Shapes
 
-The **signature contract** of a function, method, or class:
-
-```python
-# Shape = name + parameters + return type + raises
-def query(
-    self,
-    collection: str,
-    query_text: str,
-    *,
-    filters: dict | None = None,
-    limit: int = 10,
-) -> list[Result]:
-    ...
-```
-
-A shape change is anything that alters the call contract:
-adding/removing parameters, changing types, or modifying return types.
+The **signature contract** of a function, method, or class: its name, parameter names and types (including keyword-only and optional parameters), return type, and declared exceptions. A shape change is anything that alters the call contract: adding or removing parameters, changing parameter or return types, or modifying exception declarations.
 
 ### Boundaries
 
-The **module interface** — what is exported/public:
-
-```python
-# module/__init__.py
-from .service import MyService        # Public boundary
-from .routes import router            # Public boundary
-
-# Private (not exported) — can change freely
-# from .internal import _helper
-```
-
-Boundary changes affect every consumer that imports from the module.
+The **module interface** — the set of symbols explicitly exported as public. Public exports are the symbols listed in the module's index file or namespace declaration. Everything not exported is private and can change freely. Boundary changes affect every consumer that imports from the module.
 
 ### Bridges
 
-The **contracts between modules** — how they communicate:
-
-```python
-# Bridge: module_a → module_b
-# Contract: ServiceA.process() returns list[Result]
-# Consumer: ServiceB expects this shape
-
-# If ServiceA.process() changes return type:
-# → ServiceB breaks (bridge violation)
-```
+The **contracts between modules** — how one module's output becomes another module's input. A bridge connects a producer (the function or service returning data) to a consumer (the function or service expecting that data). If the producer changes the shape of its output, the consumer breaks unless it is also updated.
 
 ---
 

package/src/template/AGENTS.md

@@ -147,11 +147,40 @@ If uncertain, choose isolated and reversible changes.
 
 ---
 
-## 9. Reporting & Artifacts
+## 9. Reporting, Backlog & Artifacts
 
-- Reports: `docs/reports/YYYY-MM-DD-{slug}.md`
+The REPORT stage (stage 7) produces exactly one of three outcomes per task:
+
+```
+Work implemented this session?
+├─ YES + multi-file or architecture change → REPORT
+├─ YES + single-file cosmetic/docs-only    → SKIP
+├─ NO  + investigation/plan produced       → BACKLOG TASK
+└─ NO  + trivial lookup/question           → SKIP
+```
+
+**Key rule:** Reports record **completed work**. Backlog tasks record **planned but unexecuted work**. Never create both for the same task.
+
+### Reports (completed work)
+
+- Path: `docs/reports/YYYY-MM-DD-{slug}.md`
 - Artifacts: `docs/reports/artifacts/`
-- Learning memory: `.agent-loop/patterns.md` and `.agent-loop/patterns/*.md`
+- Trigger: implementation was done this session AND touched ≥2 files or changed architecture/patterns
+- Contents: summary, scope, changes, verification results, learned patterns
+
+### Backlog (planned but deferred work)
+
+- Index: `docs/backlog/index.md` — priority-sorted table with task state
+- Tasks: `docs/backlog/YYYY-MM-DD-{slug}.md` — one file per task
+- Trigger: investigation or planning was done BUT implementation was NOT executed (needs approval, requires decomposition, lower priority, blocked on dependency)
+- Contents: context, Action Plan, acceptance criteria, priority (P0–P3), dependencies
+- After creating a task file, add a row to `docs/backlog/index.md`
+- When a backlog task is later implemented, mark it `done` in the index and write a report for that session
+
+### Learning Memory
+
+- `.agent-loop/patterns.md` and `.agent-loop/patterns/*.md`
+- Updated during LEARN (stage 6), independent of report/backlog routing
 
-Create reports for non-trivial work (multi-file refactor, root-cause fix, architecture change).
+Full decision tree and templates: see [reasoning-kernel.md § REPORT](.agent-loop/reasoning-kernel.md).
 

package/src/template/backlog-index.md

@@ -0,0 +1,28 @@
+# Backlog
+
+Planned tasks awaiting implementation. Each task is a separate file in this folder.
+
+## Priority Levels
+
+| Priority | Meaning |
+|----------|---------|
+| **P0 — Critical** | Blocking issue or regression. Must be resolved before any other work. |
+| **P1 — High** | Important feature or fix. Next in queue after critical items. |
+| **P2 — Normal** | Standard work item. Implement when bandwidth allows. |
+| **P3 — Low** | Nice-to-have improvement. Defer until higher-priority items clear. |
+
+## Task States
+
+| State | Meaning |
+|-------|---------|
+| `planned` | Investigated and planned. Action Plan written. Ready to implement. |
+| `in-progress` | Currently being worked on. |
+| `blocked` | Cannot proceed — dependency or question unresolved. |
+| `done` | Implemented and validated. Keep for reference, then archive. |
+
+## Index
+
+<!-- Add rows as tasks are created. Keep sorted by priority then date. -->
+
+| # | Task | Priority | State | Created | File |
+|---|------|----------|-------|---------|------|