gh-christianlouis-docuelevate/AGENT_RUN_RUFF.md

Agent Pre-PR Ruff Policy

This document defines the policy for Copilot/AI Agents when creating or updating pull requests in the DocuElevate repository.

Required Steps Before Creating/Updating a PR

1. Run the Ruff Auto-Fix Script

Before creating or updating a branch or opening a PR, ALWAYS run:

./scripts/run-ruff-and-fix.sh

2. Handle Script Exit Codes

If the script exits with code 0 (success):

• ✅ All ruff checks passed or were auto-fixed
• Continue with PR creation process
• Push the branch (including any auto-fix commits)

If the script exits with code non-zero (failure):

• ❌ Stop PR creation immediately
• Do NOT open the PR
• Report the ruff failures to the human user
• Include the full ruff check output in your response
• Create an issue or report the failures for manual resolution

3. Handle Auto-Fix Commits

If the script commits fixes:

• The script will automatically commit changes with message: style: ruff auto-fixes
• Push the branch with the commit(s) before continuing PR creation
• This ensures CI sees the fixed code when the PR is opened

Example Agent Workflow

1. Clone repository and create feature branch
2. Make code changes to implement feature
3. Run: ./scripts/run-ruff-and-fix.sh
4. Check exit code:
   - If 0: Push branch and create PR
   - If non-zero: Report failures, do NOT create PR
5. Run project tests (if ruff passed)
6. If all checks pass: Create the PR
7. If any check fails: Report failures instead of creating PR

Why This Policy Exists

1. Prevent CI Failures: Ensures PRs don't break ruff checks in CI
2. Auto-Fix Minor Issues: Automatically fixes formatting and simple linting issues
3. Surface Manual Issues Early: Identifies issues that need human attention before PR creation
4. Maintain Code Quality: Enforces consistent code style across the repository

Integration with Existing CI

DocuElevate has two workflows that handle ruff:

1. .github/workflows/ci.yml (Lint Job)

   • Runs ruff check (without --fix) on all pushes and PRs
   • Fails CI if issues are found
   • Runs early in the pipeline to catch style issues before tests

2. .github/workflows/ruff-auto-fix.yml

   • Runs on PRs when Python files change
   • Automatically applies ruff --fix and ruff format
   • Commits fixes back to the PR branch
   • Posts a comment notifying the author

This agent script ensures that most issues are caught and fixed before the PR is created, reducing the need for the auto-fix workflow to intervene.

Local Development

Developers should also use this script or set up pre-commit hooks:

# Install pre-commit hooks (recommended)
pip install pre-commit
pre-commit install

# Or run manually before committing
./scripts/run-ruff-and-fix.sh

Troubleshooting

Script fails with "ruff: command not found"

The script installs ruff automatically. If this fails:

pip install ruff

Script fails with Git errors

Ensure you're in a Git repository with proper configuration:

git config user.name "Your Name"
git config user.email "your.email@example.com"

Ruff issues remain after --fix

Some issues cannot be auto-fixed (e.g., unused imports, complex logic issues). These require manual resolution:

1. Review the ruff output
2. Fix the issues manually
3. Run the script again to verify

Configuration

Ruff configuration is in pyproject.toml under [tool.ruff] and [tool.ruff.lint].

Default settings:

• Line length: 120 characters
• Target Python version: 3.11+
• Enabled rules: Pyflakes (F), pycodestyle (E, W), isort (I), bandit (S), flake8-bugbear (B), pylint (PL)

Questions?

See the Contributing Guide for more information on code quality standards and development workflow.