@oleksandr.rudnychenko/sync_loop 0.2.5 → 0.3.2

package/dist/src/template/.agent-loop/feedback.md

@@ -0,0 +1,395 @@
+# Feedback Loop (Failure Diagnosis & Patch Protocol)
+
+Behavioral patches and learning from failures. Invoked by [reasoning-kernel.md](reasoning-kernel.md) when validation fails.
+Referenced from [patterns.md](patterns.md). Writes learned fixes to patterns.md tables (quick) and [patterns/](patterns/) specs (deep).
+
+**Use when:**
+- A validation gate fails (types, tests, layers) → diagnose + patch + retry
+- `validate-env.md` or `validate-n.md` returns FAIL
+- User provides explicit score or correction on agent output
+- Same error recurs 2+ times (escalation trigger)
+- A task completes successfully (learning phase → persist pattern)
+- Refactoring changes imports/docs and tests must re-verify
+
+---
+
+## Failure Types
+
+| Type | Detection Signal | Required Response |
+|------|------------------|-------------------|
+| **Gate Failure** | Stage 1 or 2 returns FAIL | Patch root cause, rerun same gate |
+| **Shape Mismatch** | Signature/data contract breaks | Align producer/consumer contracts |
+| **Boundary Drift** | Unintended API/export changes | Restore or document intentional change |
+| **User Misalignment** | User indicates wrong behavior/scope | Re-scope and patch to requested intent |
+| **Low Coverage** | Coverage report below threshold | Add tests, retry |
+| **Bad Naming** | Files with `v1`, `new`, `old` suffixes | Rename to canonical form |
+| **Doc Change** | Documentation/import updates | Run tests to verify examples |
+| **Infinite Loop** | Same error 3+ times | Branch prune first, then escalate |
+
+---
+
+## Micro-Loop Protocol
+
+Surface-level fixes that are resolved **within CHALLENGE-TEST** without consuming the macro retry budget.
+Does NOT route through the patch contract below — self-contained.
+
+**Micro Signals:**
+
+| Signal | Fix | Budget Impact |
+|--------|-----|---------------|
+| Missing return type on new code | Add annotation based on body analysis | None |
+| `print()` / `breakpoint()` left in | Remove or convert to logging | None |
+| Unused import after refactor | Remove import line | None |
+| Formatting / whitespace issue | Auto-format | None |
+
+**Rules:**
+- Max **2 micro-fixes per gate** before escalating to macro
+- Same micro-fix needed **3×** → reclassify as macro (systemic issue)
+- Micro-fixes do NOT generate a patch contract — they are applied directly
+
+**Calibration** (from Verification Protocol):
+- Fix is **"Supported"** (evidence directly in error message) → Micro
+- Fix is **"Assumed"** (needs root cause diagnosis) → Macro
+
+---
+
+## Feedback Input Formats
+
+### From User
+
+```
+FEEDBACK ON LAST STEP
+
+Score (0-5): [rating]
+Misalignment: [what went wrong]
+Good: [what worked]
+New constraint: [rule to enforce]
+```
+
+### From Gate Failure
+
+```
+GATE FAILURE
+
+Gate: [type_check | tests | layer_rules | complexity | debug]
+Error: [specific error message]
+File: [affected file]
+Line: [line number]
+```
+
+### From Refactoring/Documentation Changes
+
+```
+REFACTORING APPLIED
+
+Changes:
+  ├─► Files moved: [list]
+  ├─► Imports updated: [count]
+  ├─► Documentation updated: [files]
+  └─► Status: [incomplete]
+
+Required Next Steps:
+  1. Run type checker
+  2. Run test suite
+  3. Verify documentation examples
+  4. Check for orphaned imports
+
+Reason: Files/imports changed → MUST verify no breakage.
+```
+
+---
+
+## Patch Contract
+
+When feedback is received, output explicit behavioral changes:
+
+```
+FEEDBACK PATCH
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Failure: [what failed]
+Root cause: [why it failed — not the symptom]
+Affected scope: [files/modules impacted]
+Minimal correction: [smallest fix that resolves root cause]
+Safety checks: [what to verify after patch]
+Retry target gate: [which gate to re-run]
+Behavioral change: [one sentence: what changes next turn]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Patch must satisfy:
+- minimal surface area
+- preserved public contracts (unless approved)
+- explicit retry target
+
+---
+
+## Learning Mechanism
+
+After each successful cycle, persist the lesson into the **Learned Patterns** section of [patterns.md](patterns.md).
+Three target tables exist — route each lesson to the correct one:
+
+### 1. Log Common Errors → patterns.md §Common Errors
+
+Add to the **Common Errors** table in `patterns.md`:
+
+```markdown
+| Symptom | Why It Happens | Prevention Heuristic |
+|---------|----------------|----------------------|
+| Missing return type | Signature drift | Add return types immediately on creation |
+| Fixture not found | conftest.py not in path | Check test fixture scope |
+```
+
+### 2. Log Auto-Fixes → patterns.md §Auto-Fixes
+
+Add to the **Auto-Fixes** table in `patterns.md`:
+
+```markdown
+| Trigger | Root Cause | Minimal Safe Fix | Auto-Apply |
+|---------|------------|------------------|------------|
+| Missing return type | `def get_name():` → no annotation | Add `-> str:` based on body | ✅ |
+| Unused import | Import left after refactor | Remove unused import line | ✅ |
+```
+
+### 3. Extract Heuristics → patterns.md §Heuristics
+
+Add to the **Heuristics** table in `patterns.md`:
+
+```markdown
+| Do More | Do Less |
+|---------|---------|
+| Check return types before type check | Assume function has correct type |
+| Verify neighbor compatibility first | Change interfaces without checking |
+```
+
+### Pattern Update Protocol (Quick Fixes → patterns.md tables)
+
+```
+On successful fix:
+  1. Identify pattern category (error, auto-fix, heuristic)
+  2. Check if pattern already exists in patterns.md
+  3. If new → append to appropriate table
+  4. If existing → update confidence/weight
+```
+
+---
+
+## Persisting to Spec Files (patterns/)
+
+Quick-fix rows land in the patterns.md tables (above). **Deeper patterns** — new code examples,
+expanded approaches, new domain rules — must be persisted into the dedicated spec files under `patterns/`.
+
+### When to Write to a Spec (vs. Index-Only)
+
+| Signal | Action | Target |
+|--------|--------|--------|
+| One-liner fix (import path, type annotation) | Row in patterns.md table only | `patterns.md §Learned Patterns` |
+| New code example or convention (>5 lines) | Add section to existing spec | `patterns/{spec}.md` |
+| New pattern ID created (P#, D#, R#) | Add entry in patterns.md + section in spec | Both |
+| Existing spec section outdated by code change | Update spec section in-place | `patterns/{spec}.md` |
+| Pattern grows complex enough to need its own spec | Create new spec file | `patterns/{new-spec}.md` |
+
+### Routing: Which Spec File Gets the Update
+
+```
+Classify the pattern → route to target file:
+
+  Core code (ports, modules, tasks, routes, DI, config, types, errors)
+    → patterns/code-patterns.md         [P1–P11]
+
+  Testing fixtures, mocks, factories, parametrize, naming
+    → patterns/testing-guide.md         [R2]
+
+  File moves, import updates, refactor checklist
+    → patterns/refactoring-workflow.md  [R1]
+
+  API docs, boundary contracts, schema generation
+    → patterns/api-standards.md         [R3]
+```
+
+### Spec File Template (for new files)
+
+When creating a **new** spec file in `patterns/`:
+
+```markdown
+# {Pattern Name}
+
+{One-line description of what this spec covers}.
+Referenced from [patterns.md](../patterns.md).
+
+---
+
+## {Section 1}
+
+{Explanation + code example}
+
+---
+
+## {Section N}
+```
+
+**Required conventions** (must match existing specs):
+1. **H1 title** — matches the pattern name in patterns.md
+2. **Backlink** — `Referenced from [patterns.md](../patterns.md).` on line 2-3
+3. **`---` separators** between sections
+4. **Code blocks** with language tags for all examples
+5. Format: runnable examples > abstract descriptions
+
+### Dual-Write Flow (Index + Spec)
+
+When a pattern is substantial enough for a spec file:
+
+```
+┌──────────────────────────────────┐
+│          LEARN phase             │
+│    (after successful fix)        │
+└───────────────┬──────────────────┘
+                │
+        Is it a quick fix?
+        (one-liner, import path,
+         type annotation)
+                │
+         ┌──────┴──────┐
+         │ YES         │ NO
+         ▼             ▼
+  ┌──────────────┐  ┌──────────────────────────────────┐
+  │ patterns.md  │  │ 1. Add/update patterns/{spec}.md │
+  │ table row    │  │    (code, explanation, examples)  │
+  │ only         │  │                                   │
+  └──────────────┘  │ 2. Update patterns.md index:      │
+                    │    - "Use when" triggers           │
+                    │    - Spec table link               │
+                    │    - Source file references         │
+                    │                                    │
+                    │ 3. Cross-ref from glossary.md      │
+                    │    if new domain terms introduced   │
+                    └──────────────────────────────────┘
+```
+
+---
+
+## Infinite Loop Detection
+
+Track error occurrences per cycle:
+
+```
+error_counts = {}
+
+for each gate failure:
+    key = f"{gate}:{file}:{error_signature}"
+    error_counts[key] += 1
+
+    if error_counts[key] >= 3:
+        → BRANCH PRUNE (see §Branch Pruning Protocol above)
+        → If already pruned this approach: ESCALATE
+```
+
+The default action on repeated failure is now **prune first, escalate second**.
+
+---
+
+## Escalation Protocol
+
+When feedback loop cannot resolve:
+
+```
+ESCALATION REQUIRED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Issue: [description]
+Attempted fixes: [list of attempts]
+Reason for escalation: [infinite loop | architecture blocker | unclear requirement]
+
+Recommended action:
+  - [specific action needed]
+  - [alternative approaches if any]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Escalate when:
+1. Retry budget exhausted (iteration > 5)
+2. Same gate fails repeatedly without meaningful delta
+3. Fix requires destructive or unapproved contract change
+
+---
+
+## State Artifacts
+
+Learned patterns are persisted in [patterns.md](patterns.md) and route to [patterns/](patterns/) specs.
+Session summaries go to `docs/reports/`.
+
+```
+.agent-loop/
+├── patterns.md                  # INDEX — pattern registry + learned fixes + pruning records
+│   ├── Pattern Registry
+│   │   ├── Core Code (P1–P11)        → patterns/code-patterns.md
+│   │   └── Process (R1–R3)           → patterns/refactoring-workflow.md,
+│   │                                   patterns/testing-guide.md,
+│   │                                   patterns/api-standards.md
+│   ├── Architecture Baseline
+│   ├── Artifact Placement
+│   └── Learned Patterns             ← FEEDBACK WRITES HERE
+│       ├── Auto-Fixes table
+│       ├── Heuristics table
+│       ├── Common Errors table
+│       └── Pruning Records table      ← BRANCH PRUNING WRITES HERE
+│
+├── patterns/                    # SPECS — detailed approaches & examples
+│   ├── code-patterns.md              # P1–P11 with examples
+│   ├── testing-guide.md              # R2 test patterns
+│   ├── refactoring-workflow.md       # R1 4-phase checklist
+│   └── api-standards.md              # R3 API/boundary standards
+│
+├── glossary.md                  # Domain terminology (cross-refs → D#/P#)
+├── feedback.md                  # THIS FILE — behavioral patches + micro-loop + branch pruning
+├── reasoning-kernel.md          # Core 7-stage loop + context clearage + transitions
+├── validate-env.md              # Stage 1: NFR validation (micro/macro annotated)
+└── validate-n.md                # Stage 2: neighbor validation
+```
+
+---
+
+## Integration with Agent Loop
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     FEEDBACK INTEGRATION                     │
+├─────────────────────────────────────────────────────────────┤
+│                                                              │
+│  reasoning-kernel.md                                         │
+│        │                                                     │
+│        ▼                                                     │
+│   CHALLENGE-TEST                                             │
+│        │                                                     │
+│  validate-env.md ─┬─► PASS ─┐                                │
+│                   └─► FAIL ─┤                                │
+│  validate-n.md ───┬─► PASS ─┤                                │
+│                   └─► FAIL ─┤                                │
+│                              ▼                               │
+│                   feedback.md (THIS)                         │
+│                              │                               │
+│                        Diagnose error                        │
+│                              │                               │
+│                        Apply patch                           │
+│                              │                               │
+│                        Retry action                          │
+│                              │                               │
+│                   ┌─► PASS → learn → persist:              │
+│                   │    ├─ quick fix → patterns.md table      │
+│                   │    └─ deep pattern → patterns/{spec}.md  │
+│                   └─► FAIL (3x) → escalate                   │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Related Documents
+
+| Document | Purpose |
+|----------|---------|
+| [patterns.md](patterns.md) | Pattern registry — learned fixes written here |
+| [reasoning-kernel.md](reasoning-kernel.md) | 7-stage loop that invokes feedback on FAIL |
+| [validate-env.md](validate-env.md) | Stage 1 NFRs — gate failures feed into this file |
+| [validate-n.md](validate-n.md) | Stage 2 neighbors — shape breaks feed into this file |
+| [glossary.md](glossary.md) | Domain terms — naming feedback references glossary |
+| [patterns/testing-guide.md](patterns/testing-guide.md) | R2: test patterns for coverage feedback |
+| [patterns/refactoring-workflow.md](patterns/refactoring-workflow.md) | R1: refactoring checklist for doc-change feedback |

package/dist/src/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/dist/src/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) |