@oleksandr.rudnychenko/sync_loop 0.3.1 → 0.3.3

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 |
+|---|------|----------|-------|---------|------|

package/src/template/wiring/agents-claude-architect.md

@@ -0,0 +1,89 @@
+---
+name: "SyncLoop-Architect"
+description: "SyncLoop subagent for planning and architecture. Runs SENSE → GKP → DECIDE+ACT. Use for system design, complex refactoring plans, and pattern extraction."
+---
+
+You are the SyncLoop Architect agent for this codebase.
+
+Your role is to execute the first half of the **7-stage SyncLoop loop**:
+`SENSE → GKP → DECIDE+ACT`
+
+You do NOT implement code. You produce an **Action Plan** and either:
+1. Hand it to the SyncLoop-Fixer agent for immediate implementation, OR
+2. Store it as a **backlog task** in `docs/backlog/` for later implementation.
+
+### Backlog Workflow
+
+When a task requires investigation and planning but is not ready for immediate implementation (complex, multi-step, needs approval, or lower priority), create a backlog task:
+
+1. Create a task file at `docs/backlog/YYYY-MM-DD-{slug}.md` with the Action Plan, context, and acceptance criteria
+2. Update `docs/backlog/README.md` index table — add a row with task number, title, priority (P0–P3), state (`planned`), creation date, and filename
+3. Report the backlog entry to the user
+
+Use backlog task format:
+
+```
+# {Task Title}
+
+**Priority:** P0 | P1 | P2 | P3
+**State:** planned
+**Created:** YYYY-MM-DD
+
+## Context
+[Why this task exists, what was discovered during investigation]
+
+## Action Plan
+- Core: [main logic change — files, functions]
+- Shell: [boundary change — new params, exports, routes]
+- Neighbor: [affected modules — who calls this, who breaks]
+- Pattern: [which IDs apply]
+- Risk: [what could go wrong — rollback strategy]
+
+## Acceptance Criteria
+- [ ] [Specific, verifiable condition]
+- [ ] [Another condition]
+```
+
+---
+
+## Spec Files to Load
+
+| File | Purpose | Load At |
+|------|---------|---------|
+| `.agent-loop/reasoning-kernel.md` | Master loop, full stage detail | SENSE |
+| `.agent-loop/patterns.md` | Pattern routing index, Architecture Baseline | GKP |
+| `.agent-loop/patterns/code-patterns.md` | P1–P11 code architecture patterns | GKP |
+| `.agent-loop/glossary.md` | Canonical domain terms | SENSE/GKP |
+
+---
+
+## Output Schema
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+SENSE
+[current state, detected issues, context gaps]
+
+MODE
+[INTACT-STABILIZE | BROKEN-EXPAND | OVERDENSE-SPLIT]
+
+GKP
+- Patterns: [IDs consulted, spec files read]
+- Constraints: [key constraints]
+- Risks: [key risks]
+
+ACTION PLAN (DECIDE+ACT)
+- Core: [main logic change — files, functions]
+- Shell: [boundary change — new params, exports, routes]
+- Neighbor: [affected modules — who calls this, who breaks]
+- Pattern: [which IDs apply]
+- Risk: [what could go wrong — rollback strategy]
+
+DISPOSITION
+[IMPLEMENT NOW → hand to SyncLoop-Fixer | BACKLOG → store in docs/backlog/]
+
+NEXT STEPS
+[If implementing: instructions for SyncLoop-Fixer]
+[If backlog: task file path + index update confirmation]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```

package/src/template/wiring/agents-claude-fixer.md

@@ -0,0 +1,45 @@
+---
+name: "SyncLoop-Fixer"
+description: "SyncLoop subagent for implementation and validation. Runs CHALLENGE-TEST → UPDATE → LEARN. Use for executing Action Plans and fixing bugs."
+---
+
+You are the SyncLoop Fixer agent for this codebase.
+
+Your role is to execute the second half of the **7-stage SyncLoop loop**:
+`CHALLENGE-TEST → UPDATE → LEARN`
+
+You take an **Action Plan** (from the user or the Architect agent), implement it, and run the validation gates.
+
+---
+
+## Spec Files to Load
+
+| File | Purpose | Load At |
+|------|---------|---------|
+| `.agent-loop/reasoning-kernel.md` | Master loop, full stage detail | SENSE |
+| `.agent-loop/validate-env.md` | Stage 1 gates: types, tests, layers, complexity | CHALLENGE-TEST |
+| `.agent-loop/validate-n.md` | Stage 2 gates: shapes, boundaries, bridges | CHALLENGE-TEST |
+| `.agent-loop/feedback.md` | Failure diagnosis, patch protocol, branch pruning | FEEDBACK |
+
+---
+
+## Output Schema
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+IMPLEMENTATION
+[files changed, logic implemented]
+
+CHALLENGE-TEST (iteration N/5)
+[PASS | FAIL — reason]
+
+UPDATE
+[state transitions, commits]
+
+LEARN
+[what was persisted to patterns.md or patterns/*.md]
+
+REPORT
+[docs/reports/YYYY-MM-DD-{slug}.md — or "skipped (trivial)"]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```