@oleksandr.rudnychenko/sync_loop 0.2.1

package/template/.agent-loop/validate-env.md

@@ -0,0 +1,332 @@
+# Validate Environment (NFRs)
+
+**Fixed Non-Functional Requirements** for solutions, code, and documentation.
+
+This is **Stage 1** of the 2-stage validation integrated into the reasoning kernel.
+
+---
+
+## Position in Reasoning Kernel
+
+```
+CHALLENGE-TEST (from reasoning-kernel.md):
+  │
+  ├─► [Stage 1] validate-env.md  ◄── YOU ARE HERE
+  │     │
+  │     ├─► Check NFRs (types, tests, layers, complexity, debug)
+  │     └─► FAIL? → feedback.md → patch → retry
+  │
+  └─► [Stage 2] validate-n.md
+        └─► Check neighbors (shapes, boundaries, bridges)
+```
+
+---
+
+## NFR Categories
+
+### Code NFRs
+
+| NFR | Requirement | Evidence | Required |
+|-----|-------------|----------|----------|
+| **Type Safety** | All functions typed, no untyped `Any` | Static type checker output | Yes |
+| **Test Coverage** | Critical paths tested | Test runner result | Yes |
+| **Layer Integrity** | No cross-layer imports | Import analysis | Yes |
+| **Complexity** | Files < 500 LOC, functions < 50 LOC | Size/complexity metrics | Warning |
+| **No Debug Code** | No print(), breakpoint(), TODO | Grep/search | Yes |
+
+### Solution NFRs
+
+| NFR | Requirement | Evidence |
+|-----|-------------|----------|
+| **Minimal Change** | Smallest diff that solves the problem | Review diff size |
+| **No Regressions** | Existing tests must pass | Test runner |
+| **Backward Compatible** | Public APIs unchanged (unless approved) | Shape check |
+| **Idiomatic** | Follows project patterns from patterns.md | Pattern match |
+
+### Documentation NFRs
+
+| NFR | Requirement | Evidence |
+|-----|-------------|----------|
+| **Docstrings** | Public functions have docstrings | AST/lint check |
+| **Type Hints** | Parameters and returns annotated | Type checker |
+| **Updated Docs** | README/docs reflect changes | Manual review |
+
+---
+
+## 2-Stage Validation Pattern
+
+Each NFR check follows this pattern:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    NFR VALIDATION                            │
+├─────────────────────────────────────────────────────────────┤
+│                                                              │
+│  STAGE 1: CHECK                                              │
+│  ───────────────                                             │
+│  Run gate command → Collect results                          │
+│                                                              │
+│  STAGE 2: FEEDBACK (if failed)                               │
+│  ─────────────────────────────                               │
+│  Diagnose error → Generate patch → Apply fix → Retry         │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Gate Execution Order
+
+1. Run gates in defined order (Type Safety → Tests → Layers → Complexity → Debug)
+2. Stop at first failure
+3. Route to [feedback.md](feedback.md) for diagnosis
+4. Patch minimally at root cause
+5. Retry the same failing gate
+6. Continue only after pass
+
+---
+
+## Per-Gate Execution Patterns
+
+### Gate 1: Type Safety
+
+**Failure class:** Micro (if error on new code only) / Macro (if existing signatures affected)
+
+Run static type checker for the project.
+
+**Commands:**
+```bash
+# {Fill in with project type check command}
+{typecheck command}
+```
+
+**2-Stage Pattern:**
+```
+STAGE 1 — CHECK:
+  Run type checker → Collect errors
+
+STAGE 2 — FEEDBACK (if failed):
+  ├─► Parse error: e.g. "Missing return type annotation"
+  ├─► Generate patch: Add return type based on body analysis
+  ├─► Apply fix
+  └─► Retry STAGE 1
+```
+
+**Auto-fixable:** Missing return types (obvious), simple type narrowing
+**Not auto-fixable:** Complex generics, protocol violations
+
+### Gate 2: Test Coverage
+
+**Failure class:** Macro (always — test failures require root cause diagnosis)
+
+Run the project test suite.
+
+**Commands:**
+```bash
+# {Fill in with project test commands}
+{test command}
+```
+
+**2-Stage Pattern:**
+```
+STAGE 1 — CHECK:
+  Run test suite → Collect failures
+
+STAGE 2 — FEEDBACK (if failed):
+  ├─► Identify failing test
+  ├─► Analyze root cause in SOURCE (never modify test)
+  ├─► Generate fix for source code
+  └─► Retry STAGE 1
+```
+
+**Rule:** Never modify tests to make them pass.
+
+**Critical Workflow:**
+```
+After ANY of these changes:
+  ├─► Code refactoring (moved files, renamed modules)
+  ├─► Import path changes
+  ├─► Documentation updates (especially imports in docs)
+  ├─► Type check fixes
+  └─► MUST run full test suite
+
+Reason: Ensure imports work, examples are valid, no broken references.
+```
+
+### Gate 3: Layer Integrity
+
+**Failure class:** Macro (always — requires architectural decision)
+
+Verify no cross-layer imports exist in the project architecture.
+
+**Project-specific rules:**
+{Fill in during bootstrap — define which layers cannot import from which.}
+
+- Routes must NOT contain business logic — delegate to services
+- Services must NOT depend on transport layer
+- Infrastructure utilities must NOT import from domain modules
+
+{Add additional project-specific layer rules here.}
+
+**2-Stage Pattern:**
+```
+STAGE 1 — CHECK:
+  Scan for cross-layer imports (e.g., infra importing domain)
+
+STAGE 2 — FEEDBACK (if failed):
+  ├─► Identify violation location
+  ├─► Refactor: extract to correct layer OR use dependency injection
+  └─► Retry STAGE 1
+```
+
+**Not auto-fixable:** Requires architectural decision.
+
+### Gate 4: Complexity
+
+**Failure class:** Macro (triggers mode switch to OVERDENSE-SPLIT)
+
+Check file and function sizes against thresholds.
+
+**2-Stage Pattern:**
+```
+STAGE 1 — CHECK:
+  Measure file LOC, function LOC, cyclomatic complexity
+
+STAGE 2 — FEEDBACK (if exceeded):
+  ├─► Identify overdense code
+  ├─► Switch to OVERDENSE-SPLIT mode
+  ├─► Decompose before proceeding
+  └─► Retry STAGE 1
+```
+
+### Gate 5: Debug Hygiene
+
+**Failure class:** Micro (always — auto-removable artifacts)
+
+Check for debug artifacts left in production code.
+
+**Commands:**
+```bash
+# {Fill in with project lint/format commands}
+{lint command}
+```
+
+**2-Stage Pattern:**
+```
+STAGE 1 — CHECK:
+  Scan for debug artifacts (print, breakpoint, TODO, etc.)
+
+STAGE 2 — FEEDBACK (if found):
+  ├─► Remove or convert to proper logging
+  └─► Retry STAGE 1
+```
+
+---
+
+## Auto-Fix Rules
+
+| NFR | Auto-Fixable | Condition |
+|-----|--------------|-----------|
+| Type Safety | Partial | Only obvious return types, simple narrowing |
+| Test Coverage | Never | Fix source, not tests |
+| Layer Integrity | Never | Requires architecture decision |
+| Complexity | Via Split | Triggers OVERDENSE-SPLIT mode |
+| Debug Code | Yes | Remove or convert to logging |
+
+---
+
+## Iteration Budget and Escalation
+
+- Max 5 full CHALLENGE-TEST iterations
+- Escalate when:
+  - Budget exhausted
+  - Same gate fails 3+ times with equivalent symptom
+  - Required fix exceeds approved scope
+
+Escalation report should include failing gate, attempted patches, and blockers.
+
+---
+
+## Output Contract
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+VALIDATE-ENV (Stage 1 of CHALLENGE-TEST)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+NFR: TYPE SAFETY
+  Check: [PASS | FAIL]
+  Feedback: [applied patch if failed, or "—"]
+  Retry: [PASS | SKIP]
+
+NFR: TEST COVERAGE
+  Check: [PASS | FAIL]
+  Feedback: [applied patch if failed, or "—"]
+  Retry: [PASS | SKIP]
+
+NFR: LAYER INTEGRITY
+  Check: [PASS | FAIL]
+  Feedback: [applied patch if failed, or "—"]
+  Retry: [PASS | SKIP]
+
+NFR: COMPLEXITY
+  Check: [PASS | WARN | FAIL]
+  Feedback: [applied patch if failed, or "—"]
+  Retry: [PASS | SKIP]
+
+NFR: DEBUG CODE
+  Check: [PASS | FAIL]
+  Feedback: [applied patch if failed, or "—"]
+  Retry: [PASS | SKIP]
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+STAGE 1 RESULT: [PASS | FAIL]
+PROCEED TO STAGE 2: [YES | NO - escalate]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+---
+
+## Integration with Reasoning Kernel
+
+```
+reasoning-kernel.md
+        │
+        ▼
+   CHALLENGE-TEST
+        │
+        ├─► Stage 1: validate-env.md (NFRs)
+        │     │
+        │     └─► Each NFR: CHECK → FEEDBACK → RETRY
+        │
+        └─► Stage 2: validate-n.md (Neighbors)
+              │
+              └─► Each check: CHECK → FEEDBACK → RETRY
+```
+
+**Flow on failure:**
+1. NFR check fails
+2. Invoke `feedback.md` with error context
+3. Generate and apply patch
+4. Retry the same NFR check
+5. If still fails after 3 retries → escalate
+
+---
+
+## Common Failure Patterns
+
+| Symptom | Likely Cause | Preferred Fix |
+|---------|--------------|---------------|
+| Recurrent type failures | Incomplete interface update | Update all impacted signatures |
+| Passing tests but failing layers | Hidden architectural shortcut | Restore layer boundaries |
+| Complexity spike after quick fix | Accretive patching | Switch to OVERDENSE-SPLIT mode |
+
+---
+
+## Related Documents
+
+| Document | Purpose |
+|----------|---------|
+| [reasoning-kernel.md](reasoning-kernel.md) | Full loop orchestration |
+| [validate-n.md](validate-n.md) | Neighbor compatibility stage |
+| [feedback.md](feedback.md) | Patch generation and escalation |

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

@@ -0,0 +1,321 @@
+# Validate Neighbors (Stage 2)
+
+Validation of **shapes, boundaries, and bridge interfaces** when modifying shared code.
+
+This is **Stage 2** of the 2-stage validation integrated into the reasoning kernel.
+
+---
+
+## Position in Reasoning Kernel
+
+```
+CHALLENGE-TEST (from reasoning-kernel.md):
+  │
+  ├─► [Stage 1] validate-env.md
+  │     └─► Check NFRs (types, tests, layers, docs)
+  │
+  └─► [Stage 2] validate-n.md  ◄── YOU ARE HERE
+        │
+        ├─► Check shapes (function signatures)
+        ├─► Check boundaries (module exports)
+        ├─► Check bridges (cross-module contracts)
+        └─► FAIL? → feedback.md → patch → retry
+```
+
+---
+
+## When to Run
+
+- When modifying **any public interface** (function signatures, class APIs)
+- When changing **module boundaries** (adding/removing exports)
+- When creating **new modules** or **moving code between modules**
+- Before merging changes that touch **multiple modules**
+
+### Neighbor Map
+
+{Fill in during bootstrap with actual project coupling paths.}
+
+Key coupling paths to track:
+
+```
+routes/* ──► services/* ──► repositories/* / database
+                 │
+                 ├──► external adapters (APIs, integrations)
+                 ├──► utilities (logging, audit, helpers)
+                 └──► background workers / job queues
+```
+
+When modifying any of these, check all neighbors in the coupling path.
+
+---
+
+## Core Concepts
+
+### 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.
+
+### 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.
+
+### 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)
+```
+
+---
+
+## 2-Stage Validation Pattern
+
+Each neighbor check follows this pattern:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                  NEIGHBOR VALIDATION                         │
+├─────────────────────────────────────────────────────────────┤
+│                                                              │
+│  STAGE 1: CHECK                                              │
+│  ───────────────                                             │
+│  Identify neighbors → Analyze shapes → Verify compatibility  │
+│                                                              │
+│  STAGE 2: FEEDBACK (if failed)                               │
+│  ─────────────────────────────                               │
+│  Diagnose break → Update callers first → Retry               │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Per-Check Execution Patterns
+
+### Check 1: Shape Compatibility
+
+**2-Stage Pattern:**
+```
+STAGE 1 — CHECK:
+  Compare before/after signatures → Classify change type
+
+STAGE 2 — FEEDBACK (if BREAKING):
+  ├─► Identify all callers
+  ├─► Generate patches for each caller
+  ├─► Apply caller updates FIRST
+  ├─► Then apply source change
+  └─► Retry STAGE 1
+```
+
+For each changed function/class:
+
+```
+SHAPE CHECK: [function_name]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Before:
+  def query(collection: str, query: str) -> list[dict]
+
+After:
+  def query(collection: str, query: str) -> list[Result]
+
+Change Type: [BREAKING | ADDITIVE | COMPATIBLE]
+
+Callers Affected:
+  - module_a/services.py:45 → NEEDS UPDATE
+  - module_b/services.py:78 → COMPATIBLE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### Check 2: Boundary Integrity
+
+**2-Stage Pattern:**
+```
+STAGE 1 — CHECK:
+  Verify __init__.py exports → Check for accidental exposure
+
+STAGE 2 — FEEDBACK (if violation):
+  ├─► Remove accidental exports OR
+  ├─► Properly document new exports
+  └─► Retry STAGE 1
+```
+
+```
+BOUNDARY CHECK: [module]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Exports:
+  ✅ MyService (public, stable)
+  ✅ router (public, stable)
+  ⚠️ ResultModel (newly exported — verify callers)
+
+Internal (not exported):
+  ✅ _build_filters (private, can change)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### Check 3: Bridge Contracts
+
+**2-Stage Pattern:**
+```
+STAGE 1 — CHECK:
+  Verify cross-module contracts still hold
+
+STAGE 2 — FEEDBACK (if broken):
+  ├─► Analyze contract requirements
+  ├─► Update either producer or consumers
+  └─► Retry STAGE 1
+```
+
+```
+BRIDGE CHECK: [source] → [target]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Contract: ServiceB calls ServiceA.process()
+Expected: list[Result] with fields [id, text, score]
+Actual: list[Result] with fields [id, text, score, metadata]
+
+Compatibility: ✅ ADDITIVE (new field, no breakage)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+---
+
+## Change Classification
+
+| Type | Description | Action Required |
+|------|-------------|-----------------|
+| **COMPATIBLE** | No signature change | None |
+| **ADDITIVE** | New optional params, new fields | Verify callers handle gracefully |
+| **BREAKING** | Changed types, removed params | Update all callers |
+
+### Breaking Change Protocol
+
+When a breaking change is detected:
+
+1. **Identify all callers** (grep/search for usages)
+2. **Update callers first** (before changing source)
+3. **Run validate-env** (ensure no regressions)
+4. **Apply source change**
+5. **Run validate-env again** (final verification)
+
+---
+
+## Coupling Strength Definitions
+
+Track coupling between modules to assess impact:
+
+| Coupling | Definition | Example |
+|----------|------------|---------|
+| **Strong** | Direct function calls, shared types | Service calls another service |
+| **Medium** | Shared infrastructure (same DB tables, collections) | Two modules writing the same store |
+| **Weak** | Only via events, tasks, or async messages | Background job triggers downstream module |
+
+---
+
+## Output Contract
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+VALIDATE-N (Stage 2 of CHALLENGE-TEST)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+CHANGED MODULE: [module name]
+
+NEIGHBORS:
+  - [module1]: [weak | medium | strong] coupling
+  - [module2]: [weak | medium | strong] coupling
+
+CHECK: SHAPES
+  - [function1]: [COMPATIBLE | ADDITIVE | BREAKING]
+  - [function2]: [COMPATIBLE | ADDITIVE | BREAKING]
+  Feedback: [applied patch or "—"]
+
+CHECK: BOUNDARIES
+  Status: [INTACT | MODIFIED]
+  Feedback: [applied patch or "—"]
+
+CHECK: BRIDGES
+  Status: [VALID | BROKEN]
+  Feedback: [applied patch or "—"]
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+STAGE 2 RESULT: [PASS | FAIL]
+PROCEED: [YES → UPDATE phase | NO → escalate]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+---
+
+## Typical Corrections
+
+| Failure Type | Correction Strategy |
+|--------------|---------------------|
+| Shape mismatch | Align shared model/signature across producer and consumers |
+| Boundary drift | Restore intended exports and update docs |
+| Bridge mismatch | Normalize adapter/mapper at integration boundary |
+
+---
+
+## Integration with Reasoning Kernel
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    VALIDATION CHAIN                          │
+├─────────────────────────────────────────────────────────────┤
+│                                                              │
+│  1. reasoning-kernel.md                                      │
+│     └─► Plan action, identify affected modules               │
+│                                                              │
+│  2. validate-env.md (Stage 1)                                │
+│     └─► Run quality gates                                    │
+│                                                              │
+│  3. validate-n.md (THIS — Stage 2)                           │
+│     └─► Check shapes, boundaries, bridges                    │
+│     └─► If BREAKING → update callers first                   │
+│                                                              │
+│  4. On FAIL → feedback.md                                    │
+│     └─► Apply patches, retry                                 │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Related Documents
+
+| Document | Purpose |
+|----------|---------|
+| [validate-env.md](validate-env.md) | Stage 1 gates |
+| [feedback.md](feedback.md) | Retry and escalation logic |
+| [patterns/refactoring-workflow.md](patterns/refactoring-workflow.md) | Safe dependency and import movement |