Matas/fix/fix actions

.github/workflows/docs.yaml

@@ -68,7 +68,7 @@ jobs:
       url: ${{ steps.deployment.outputs.page_url }}
     runs-on: ubuntu-latest
     needs: build
-    if: github.ref == 'refs/heads/main'
+    if: github.ref == 'refs/heads/main' && github.repository == 'warestack/watchflow'
     steps:
       # Deploy to GitHub Pages
       - name: "Deploy to GitHub Pages"

.github/workflows/tests.yaml

@@ -38,6 +38,9 @@ jobs:
 
       # Run all tests with coverage
       - name: "Run all tests"
+        env:
+          OPENAI_API_KEY: "mock-key-for-ci"
+          USE_MOCK_DATA: "True"
         run: |
           echo "Running unit and integration tests with coverage..."
           uv run pytest tests/unit/ tests/integration/ \

.pre-commit-config.yaml

@@ -2,50 +2,30 @@ default_stages:
   - pre-commit
   - pre-push
 
-# Configuration for pre-commit hooks
 repos:
-  # General hooks from the pre-commit-hooks repository
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v5.0.0
+    rev: v6.0.0
     hooks:
       - id: trailing-whitespace
-        # Removes any trailing whitespace from lines in text files
       - id: end-of-file-fixer
-        # Ensures files end with a newline
       - id: check-yaml
         exclude: '^helm-chart/templates.*\.yaml$|^mkdocs\.yml$'
-        # Checks YAML files for syntax errors
       - id: check-json
-        # Checks JSON files for syntax errors
-      - id: check-ast
-        name: "Check Python syntax (AST validation)"
-        # Validates that Python files have valid syntax
+      - id: check-added-large-files
 
-  # Ruff hooks for Python linting and formatting
+  # Ruff: The One Tool to Rule Them All
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.9.9
+    rev: v0.3.0
     hooks:
-      # First, run ruff format - won't change imports but will format them
-      - id: ruff-format
-        name: "Format code (without changing imports)"
-
-      # Then, use a single ruff pass for both import sorting and linting
+      # Linter (Fixes imports, modernizes syntax, checks bugs)
       - id: ruff
-        name: "Linting and import sorting"
-        args: ["--fix"]
-
-  # Pyupgrade: Check and fix Python version incompatibilities and outdated syntax
-  - repo: https://github.com/asottile/pyupgrade
-    rev: v3.15.2
-    hooks:
-      - id: pyupgrade
-        name: "Upgrade syntax for Python 3.12+"
-        args: [--py312-plus]
-        # Auto-fixes outdated syntax to Python 3.12+ compatible code
+        args: [--fix, --exit-non-zero-on-fix]
+      # Formatter (Replaces Black)
+      - id: ruff-format
 
-  # Conventional pre-commit hooks for commit messages
+  # Convention Enforcement
   - repo: https://github.com/compilerla/conventional-pre-commit
-    rev: v4.0.0
+    rev: v4.3.0
     hooks:
       - id: conventional-pre-commit
         stages: [commit-msg]

.watchflow/rules.yaml

@@ -26,10 +26,19 @@ rules:
     enabled: true
     severity: "high"
     event_types: ["pull_request"]
+    parameters:
+      critical_owners: []
+
+  - description: "When a PR modifies paths with CODEOWNERS, those owners must be added as reviewers"
+    enabled: true
+    severity: "high"
+    event_types: ["pull_request"]
+    parameters:
+      require_code_owner_reviewers: true
 
   - description: "No direct pushes to main branch - all changes must go through PRs"
     enabled: true
     severity: "critical"
     event_types: ["push"]
     parameters:
-      allow_force_push: false
+      no_force_push: true

CONTRIBUTING.md

@@ -1,231 +1,83 @@
 # Contributing to Watchflow
 
-Welcome to Watchflow! We're building the future of agentic DevOps governance. This guide will help you contribute
-effectively to our advanced multi-agent system.
+Thanks for considering contributing. Watchflow is a **rule engine** for GitHub—rules in YAML, enforcement on PR and push. We aim for **maintainer-first** docs and code: tech-forward, slightly retro, no marketing fluff. The hot path is condition-based (no LLM for rule evaluation); optional AI is used for repo analysis and feasibility suggestions. See [README](README.md) and [docs](docs/) for the supported logic and architecture.
 
-## 🎯 Our Vision
+---
 
-Watchflow implements cutting-edge agentic AI techniques for DevOps governance, combining:
-- **Advanced Multi-Agent Systems** with sophisticated coordination patterns
-- **Hybrid Intelligence** (static rules + LLM reasoning)
-- **Context-Aware Decision Making** with temporal and spatial awareness
-- **Regression Prevention** to avoid duplicate violations
-- **Enterprise-Grade Policy Coverage** based on real-world research
+## Direction and scope
 
-## Architecture Overview
+- **Rule engine** — Conditions map parameter keys to built-in logic (e.g. `require_linked_issue`, `max_lines`, `require_code_owner_reviewers`). New conditions live in `src/rules/conditions/` and are registered in `src/rules/registry.py` and `src/rules/acknowledgment.py`.
+- **Webhooks** — Delivery ID–based dedup so handler and processor both run; welcome comment when no rules file exists.
+- **API** — Repo analysis and proceed-with-PR support `installation_id` so install-flow users don’t need a PAT.
+- **Docs** — All MD files should speak to engineers: direct, no fluff, immune-system framing (Watchflow as necessary governance, not “another AI tool”).
 
-### Design Patterns We Use
-- **Agent Pattern**: Each agent has specific responsibilities and interfaces
-- **Strategy Pattern**: Dynamic validation strategy selection
-- **Observer Pattern**: Event-driven agent coordination
-- **Command Pattern**: Action execution with undo capabilities
-- **Factory Pattern**: Dynamic agent and validator creation
-- **Decorator Pattern**: Cross-cutting concerns (logging, metrics, retry)
-- **State Machine Pattern**: Agent lifecycle management
+---
 
-## Getting Started
+## Getting started
 
 ### Prerequisites
+
 - Python 3.12+
-- OpenAI API key
-- LangSmith account (for tracing)
-- GitHub App setup
+- [uv](https://docs.astral.sh/uv/) (recommended) or pip
+- OpenAI API key (for repo analysis and feasibility agents)
+- LangSmith (optional, for agent debugging)
+- GitHub App credentials (for local webhook testing; see [LOCAL_SETUP.md](LOCAL_SETUP.md))
+
+### Development setup
 
-### Development Setup
 ```bash
-# Clone and setup
 git clone https://github.com/warestack/watchflow.git
 cd watchflow
 uv sync
-
-# Environment setup
 cp .env.example .env
-# Add your API keys to .env
-
-# Run tests
-uv run pytest
-
-# Start development server
-uv run python -m src.main
-```
-
-## Advanced Techniques We're Implementing
-
-### 1. Sophisticated Agent Coordination
-- **Hierarchical Agent Orchestration**: Supervisor agents coordinate specialized sub-agents
-- **Conflict Resolution**: Multi-agent decision synthesis with confidence scoring
-- **Dynamic Agent Composition**: Runtime agent creation based on context
-- **Agent Communication Protocols**: Message passing with typed interfaces
-
-### 2. Advanced LLM Integration
-- **Chain-of-Thought Reasoning**: Step-by-step decision making
-- **ReAct Pattern**: Reasoning + Acting in agent workflows
-- **Few-Shot Learning**: Dynamic prompt examples based on context
-- **Structured Output Validation**: Pydantic models with retry logic
-- **Prompt Injection Mitigation**: Security-first prompt engineering
-
-### 3. Context-Aware Intelligence
-- **Temporal Context**: Historical decision patterns and outcomes
-- **Spatial Context**: Repository, team, and organizational context
-- **Developer Context**: Experience level, contribution patterns, team dynamics
-- **Business Context**: Project phase, compliance requirements, risk profiles
-
-### 4. Regression Prevention System
-- **Violation Deduplication**: Avoid sending same violations repeatedly
-- **State Tracking**: Track violation resolution status across events
-- **Smart Notifications**: Context-aware escalation and reminder systems
-- **Learning from Feedback**: Adapt based on developer responses
-
-## Development Guidelines
-
-### Code Quality Standards
-- **Type Hints**: All functions must have complete type annotations
-- **Async/Await**: Use async patterns throughout for performance
-- **Error Handling**: Comprehensive error handling with structured logging
-- **Testing**: Unit tests, integration tests, and agent behavior tests
-- **Documentation**: Docstrings with examples and type information
-
-### Agent Development
-```python
-class AdvancedAgent(BaseAgent):
-    """Example of advanced agent implementation."""
-
-    def __init__(self, **kwargs):
-        super().__init__(**kwargs)
-        self.context_store = ContextStore()
-        self.learning_engine = LearningEngine()
-        self.regression_preventer = RegressionPreventer()
-
-    async def execute(self, **kwargs) -> AgentResult:
-        """Execute with advanced techniques."""
-        # 1. Context enrichment
-        context = await self.context_store.enrich(kwargs)
-
-        # 2. Regression check
-        if await self.regression_preventer.is_duplicate(context):
-            return AgentResult(success=True, message="Duplicate violation prevented")
-
-        # 3. Advanced reasoning
-        result = await self._advanced_reasoning(context)
-
-        # 4. Learning update
-        await self.learning_engine.update(result, context)
-
-        return result
-```
+# Add API keys and GitHub App credentials to .env
 
-### Design Pattern Examples
-```python
-# Strategy Pattern for validation
-class ValidationStrategy(ABC):
-    @abstractmethod
-    async def validate(self, context: ValidationContext) -> ValidationResult:
-        pass
-
-class LLMValidationStrategy(ValidationStrategy):
-    async def validate(self, context: ValidationContext) -> ValidationResult:
-        # Advanced LLM reasoning with CoT
-        pass
-
-# Observer Pattern for agent coordination
-class AgentCoordinator:
-    def __init__(self):
-        self.observers: List[AgentObserver] = []
-
-    def notify_agents(self, event: AgentEvent):
-        for observer in self.observers:
-            asyncio.create_task(observer.handle_event(event))
+uv run pytest tests/unit/ tests/integration/ -v   # run tests
+uv run python -m src.main                          # start server
 ```
 
-## Contribution Areas
-
-### High-Priority Issues
-1. **Advanced Agent Coordination** - Implement sophisticated multi-agent orchestration
-2. **Regression Prevention System** - Build violation deduplication and state tracking
-3. **Context-Aware Intelligence** - Enhance context enrichment and decision making
-4. **Learning Agent Implementation** - Add feedback-based policy adaptation
-5. **Enterprise Policy Coverage** - Implement 70+ real-world enterprise policies
-
-### Advanced Features
-- **Agent Specialization**: Domain-specific agents (security, compliance, performance)
-- **Cross-Platform Support**: Extend beyond GitHub to GitLab, Azure DevOps
-- **Advanced Analytics**: Decision quality metrics and performance optimization
-- **Custom Agent Development**: Framework for users to create custom agents
-
-## Testing Strategy
-
-### Agent Testing
-```python
-@pytest.mark.asyncio
-async def test_agent_coordination():
-    """Test sophisticated agent coordination."""
-    coordinator = AgentCoordinator()
-    result = await coordinator.coordinate_agents(
-        task="complex_policy_evaluation",
-        context=test_context
-    )
-    assert result.confidence > 0.8
-    assert len(result.agent_decisions) > 0
-```
+See [DEVELOPMENT.md](DEVELOPMENT.md) for full env vars and [LOCAL_SETUP.md](LOCAL_SETUP.md) for GitHub App and ngrok.
 
-### Integration Testing
-- **End-to-End Workflows**: Complete agent orchestration scenarios
-- **Performance Testing**: Latency and throughput under load
-- **Regression Testing**: Ensure new features don't break existing functionality
+---
 
-## 📚 Resources
+## Code and architecture
 
-### Academic Foundation
-- Our thesis: "Watchflow: Agentic DevOps Governance"
-- Multi-Agent Systems literature
-- LLM reasoning techniques (CoT, ReAct, etc.)
-- DevOps governance best practices
+- **Conditions** — One class per rule type in `src/rules/conditions/`; each has `name`, `parameter_patterns`, `event_types`, and `evaluate()` / `validate()`. Registry maps parameter keys to condition classes.
+- **Rule loading** — `src/rules/loaders/github_loader.py` reads `.watchflow/rules.yaml` from the default branch; normalizes aliases (e.g. `max_changed_lines` → `max_lines`).
+- **PR processor** — Loads rules, enriches event with PR files and CODEOWNERS content, passes **Rule objects** (with condition instances) to the engine so conditions aren’t stripped.
+- **Task queue** — Task ID includes `delivery_id` when present so handler and processor get distinct IDs per webhook delivery.
 
-### Technical Resources
-- [LangGraph Documentation](https://langchain-ai.github.io/langgraph/)
-- [OpenAI API Best Practices](https://platform.openai.com/docs/guides/production-best-practices)
-- [Pydantic Documentation](https://docs.pydantic.dev/)
-- [FastAPI Documentation](https://fastapi.tiangolo.com/)
+---
 
-## Community
+## Running tests
 
-- **Discussions**: Use GitHub Discussions for architecture questions
-- **Issues**: Report bugs and request features
-- **Pull Requests**: Submit improvements and new features
-- **Discord**: Join our community for real-time collaboration
+```bash
+uv sync --all-extras
+uv run pytest tests/unit/ tests/integration/ -v
+```
 
-## Pull Request Process
+Run from repo root with the project venv active (or use `just test-local` / see DEVELOPMENT.md) so the correct interpreter and deps are used.
 
-1. **Fork** the repository
-2. **Create** a feature branch (`git checkout -b feature/amazing-feature`)
-3. **Implement** with tests and documentation
-4. **Run** tests (`uv run pytest`)
-5. **Commit** changes (`git commit -m 'Add amazing feature'`)
-6. **Push** to branch (`git push origin feature/amazing-feature`)
-7. **Open** a Pull Request
+---
 
-### PR Requirements
-- [ ] All tests pass
-- [ ] Type hints added
-- [ ] Documentation updated
-- [ ] No regression in performance
-- [ ] Agent behavior tests included
+## Pull requests
 
-## Recognition
+1. Branch from `main` (or the current target branch).
+2. Keep changes focused; prefer multiple small PRs over one large one.
+3. Ensure tests pass and pre-commit hooks (ruff, etc.) pass.
+4. Use conventional commit style where possible (e.g. `fix(rules): preserve conditions in engine`).
 
-Contributors will be recognized in:
-- README contributors section
-- Release notes
-- Academic papers (where applicable)
-- Community highlights
+---
 
-## Questions?
+## Docs
 
-- **Architecture**: Open a discussion
-- **Implementation**: Ask in issues
-- **Research**: Contact maintainers
-- **Community**: Join Discord
+- **Tone** — Tech-forward, slightly retro, maintainer-first. Speak to engineers, not marketing. “Immune system” framing: Watchflow as necessary governance, not another AI tool.
+- **Accuracy** — Parameter names and conditions in docs must match the code (see `src/rules/registry.py` and condition modules).
+- **Examples** — Use real parameter names: `require_linked_issue`, `max_lines`, `require_code_owner_reviewers`, `no_force_push`, etc.
 
 ---
 
-Thank you for contributing to Watchflow!
+## Questions
+
+- [GitHub Discussions](https://github.com/warestack/watchflow/discussions)
+- [GitHub Issues](https://github.com/warestack/watchflow/issues)