Implement status check violation detection

.watchflow/rules.yaml

@@ -0,0 +1,84 @@
+rules:
+  - id: test-always-fail
+    name: "Test Rule - Always Fail"
+    description: "This rule should always fail to test if rule evaluation is working"
+    enabled: true
+    severity: high
+    event_types: ["pull_request"]
+    conditions:
+      - type: "min_description_length"
+        parameters:
+          min_description_length: 999999  # Impossibly high requirement
+
+  - id: status-check-ci-tests
+    name: "Require CI Tests"
+    description: "All CI tests must pass before merging"
+    enabled: true
+    severity: high
+    event_types: ["pull_request", "status"]
+    conditions:
+      - type: "required_checks"
+        parameters:
+          required_checks:
+            - "Lint code and README files"
+            - "Run pre-commit hooks / Lint code and README files"
+
+  - id: status-check-security
+    name: "Security Checks Required"
+    description: "Security scans must pass before merging"
+    enabled: true
+    severity: high
+    event_types: ["status"]
+    conditions:
+      - type: "required_checks"
+        parameters:
+          required_checks:
+            - "security/scan"
+            - "vulnerability-check"
+
+  - id: status-check-code-quality
+    name: "Code Quality Gates"
+    description: "Code quality checks must pass before merging"
+    enabled: true
+    severity: medium
+    event_types: ["status"]
+    conditions:
+      - type: "required_checks"
+        parameters:
+          required_checks:
+            - "codecov/patch"
+            - "codeclimate"
+            - "sonarqube"
+
+  - id: conventional-commits
+    name: "Conventional Commit Format"
+    description: "Commit messages must follow conventional commit format"
+    enabled: false  # Disabled - no validator implemented yet
+    severity: medium
+    event_types: ["push"]
+    conditions:
+      - type: "commit_message_pattern"
+        parameters:
+          commit_message_pattern: "^(feat|fix|docs|style|refactor|test|chore)(\\(.+\\))?: .{1,50}"
+
+  - id: pr-description-required
+    name: "Pull Request Description Required"
+    description: "Pull requests must have a meaningful description"
+    enabled: true
+    severity: low
+    event_types: ["pull_request"]
+    conditions:
+      - type: "min_description_length"
+        parameters:
+          min_description_length: 20
+
+  - id: no-direct-main-push
+    name: "No Direct Push to Main"
+    description: "Prevent direct pushes to main branch - use pull requests"
+    enabled: true
+    severity: high
+    event_types: ["push"]
+    conditions:
+      - type: "protected_branches"
+        parameters:
+          protected_branches: ["main", "master"]

DEVELOPMENT.md

@@ -2,6 +2,12 @@
 
 This guide covers setting up the Watchflow development environment for local development and testing.
 
+## Quick Start
+
+🚀 **New to Watchflow?** Start with our [Local Development Setup Guide](./LOCAL_SETUP.md) for a complete end-to-end setup including GitHub App configuration and webhook testing.
+
+This document covers advanced development topics and workflow.
+
 ## Prerequisites
 
 - Python 3.12 or higher
@@ -22,6 +28,7 @@ cd watchflow
 ### 2. Create Virtual Environment
 
 Using uv (recommended):
+
 ```bash
 # Create and activate virtual environment
 uv venv
@@ -34,6 +41,7 @@ uv sync
 ```
 
 Or using pip:
+
 ```bash
 # Create virtual environment
 python -m venv .venv
@@ -118,8 +126,10 @@ Create a GitHub App for development:
    - Issue comment
    - Pull request
    - Push
+   - Status
 
 6. **Generate private key** and encode it:
+
    ```bash
    cat /path/to/private-key.pem | base64 | tr -d '\n'
    ```
@@ -145,6 +155,7 @@ For debugging AI agents:
 1. Create a [LangSmith](https://langsmith.com/) account
 2. Get your API key
 3. Add to environment:
+
    ```bash
    LANGCHAIN_TRACING_V2=true
    LANGCHAIN_API_KEY=your-langsmith-api-key
@@ -193,6 +204,41 @@ uv run ruff format src/
 uv run mypy src/
 ```
 
+### Pre-commit Hooks
+
+This project uses pre-commit hooks to ensure code quality and consistency. The hooks automatically run on every commit and include:
+
+- **Trailing whitespace removal** - Cleans up extra whitespace
+- **End of file fixer** - Ensures files end with newlines
+- **YAML/JSON validation** - Checks syntax
+- **Ruff formatting and linting** - Formats code and sorts imports
+- **Conventional commit validation** - Ensures commit messages follow conventional format
+
+#### Setup Pre-commit Hooks
+
+```bash
+# Install pre-commit hooks (run once after cloning)
+uv run pre-commit install
+
+# Also install commit message validation
+uv run pre-commit install --hook-type commit-msg
+```
+
+#### Using Pre-commit Hooks
+
+```bash
+# Hooks run automatically on commit, but you can run them manually:
+uv run pre-commit run --all-files
+
+# Run on specific files
+uv run pre-commit run --files src/main.py
+
+# Skip hooks for a commit (not recommended)
+git commit --no-verify -m "commit message"
+```
+
+The hooks will prevent commits if any issues are found. Most formatting issues are automatically fixed, so you just need to stage the changes and commit again.
+
 ### Testing
 
 The project includes comprehensive tests that run **without making real API calls** by default:
@@ -212,7 +258,7 @@ pytest tests/integration/
 
 ### Test Structure
 
-```
+```txt
 tests/
 ├── unit/                     # ⚡ Fast unit tests (mocked OpenAI)
 │   └── test_feasibility_agent.py
@@ -235,16 +281,6 @@ pytest tests/integration/ -m integration
 
 _Note: Real API tests make actual OpenAI calls and will cost money. They're disabled by default in CI/CD._
 
-### Pre-commit Hooks
-
-```bash
-# Install pre-commit hooks
-uv run pre-commit install
-
-# Run manually
-uv run pre-commit run --all-files
-```
-
 ## Testing AI Agents
 
 ### Rule Evaluation Testing
@@ -282,6 +318,15 @@ rules:
     event_types: [pull_request]
     parameters:
       test_param: "test_value"
+
+  - id: status-check-required
+    name: Status Check Required
+    description: All PRs must pass required status checks
+    enabled: true
+    severity: high
+    event_types: [pull_request]
+    parameters:
+      required_checks: ["ci/test", "lint"]
 ```
 
 ## Debugging
@@ -319,20 +364,23 @@ Test webhook delivery:
 ### GitHub App Permissions
 
 If webhooks aren't being received:
+
 1. Verify webhook URL is accessible
 2. Check GitHub App permissions
 3. Verify webhook secret matches
 
 ### AI Agent Issues
 
 If agents aren't working:
+
 1. Verify OpenAI API key
 2. Check LangSmith configuration
 3. Review agent logs for errors
 
 ### Development Environment
 
 If dependencies aren't working:
+
 1. Ensure Python 3.12+
 2. Try recreating virtual environment
 3. Check uv/pip installation
@@ -352,6 +400,7 @@ locust -f load_test.py --host=http://localhost:8000
 ### Agent Performance
 
 Monitor agent performance with LangSmith:
+
 - Token usage per request
 - Response times
 - Error rates