Repository-Aware Rules

Repository-aware rules let a team version review guidance with the repository without adding hidden memory or automatic documentation ingestion. The supported format is .ai-review.yml with bounded review.rules.

Rules are advisory prompt constraints. They guide provider attention, but findings still require concrete diff/context evidence.

Default Mode

AI_REVIEW_REPOSITORY_CONTEXT supports two values:

Use off when a pipeline should avoid repo-derived prompt context:

AI_REVIEW_REPOSITORY_CONTEXT=off ai-review run --mode mr

This flag does not override AI_REVIEW_CONTEXT_MODE. If AI_REVIEW_CONTEXT_MODE=diff+semantic is enabled, semantic diagnostics can still be included in prompt context; set AI_REVIEW_CONTEXT_MODE=diff-only too when avoiding semantic analyzer context.

This flag is also separate from review lenses. Repo-local rules do not enable review lenses; lens behavior remains controlled by AI_REVIEW_ENABLE_LENSES and AI_REVIEW_LENSES.

.ai-review.yml Rules

Place .ai-review.yml at the repository root:

version: 1
defaults:
  provider: openai
  model: gpt-4o-mini
  feedback_mode: artifact-only
  review_context_mode: diff-only
  include_globs:
    - src/**
  exclude_globs:
    - vendor/**
    - node_modules/**
review:
  rules:
    - id: privacy.no-raw-payload-logging
      severity: error
      scope:
        - "src/api/**"
        - "src/jobs/**"
      instruction: "When changed code handles request bodies, uploaded files, payment metadata, or imported customer records, flag new logging or exception paths that could expose raw values."
    - id: tests.runtime-behavior-needs-regression
      severity: warning
      scope:
        - "src/**/*.py"
        - "tests/**/*.py"
      instruction: "When runtime behavior changes, verify that tests cover the pre-fix failure mode and the observable behavior users rely on."
    - id: dependencies.require-upgrade-rationale
      severity: warning
      scope:
        - "pyproject.toml"
        - "uv.lock"
        - "package.json"
        - "package-lock.json"
      instruction: "For dependency additions or major upgrades, check whether the diff explains compatibility, rollout, and fallback risk for the affected runtime."
    - id: architecture.keep-order-state-in-service-layer
      severity: info
      scope:
        - "src/orders/**"
        - "src/api/**"
      instruction: "When order state changes, prefer the existing service layer over direct state transitions in request handlers, scheduled jobs, or view code."

Each rule includes:

PatchPatrol accepts at most 50 configured repo-local rules and renders at most 12 matched rules per prompt/chunk. Rendered rules share the AI_REVIEW_MAX_SUPPORTING_CONTEXT_BYTES budget with deterministic preflight hints, supporting code evidence, semantic diagnostics, and repository overview context.

include_globs and exclude_globs narrow reviewed files before rule matching. Rule scope then controls which rules match the remaining reviewed paths.

Do not put secrets, tokens, provider endpoints, executable hooks, private customer identifiers, or hidden approval rules into .ai-review.yml.

Reading The Output

ai-review.json is the source of truth. Markdown, HTML, GitLab MR summaries, and GitHub Actions job summaries are compact renderings from the same JSON metadata.

Look under meta.repository_context for:

• mode: on or off.
• policy_file and policy_file_status.
• rule counts: configured, matched, included, omitted, and unmatched.
• matched and included rule identities: id, severity, and scope.
• context_budget.max_bytes, used_bytes, truncated, and payload_count.
• context_sources entries for repo_rules, preflight_hints, supporting_code, semantic_diagnostics, and repository_overview.
• compact reason_codes.
• persisted_memory.enabled=false and entries_loaded=0.

Raw rule instructions are not stored in normal artifacts by default. Artifacts may show rule ids, severities, scopes, counts, source categories, and reason codes so reviewers can audit what happened without exposing the full rule text.

CI And Local Examples

GitLab artifact-first:

patchpatrol_review:
  image: registry.patchpatrol.ai/patchpatrol:latest
  rules:
    - if: '$CI_MERGE_REQUEST_IID'
  variables:
    AI_REVIEW_FEEDBACK_MODE: "artifact-only"
    AI_REVIEW_OUTPUT_DIR: ".ai-review"
    AI_REVIEW_REPOSITORY_CONTEXT: "on"
  script:
    - ai-review run --mode mr
  artifacts:
    when: always
    paths:
      - .ai-review/ai-review.json
      - .ai-review/ai-review.md
      - .ai-review/ai-review.html

GitHub Actions artifact-first:

- name: Run bounded PatchPatrol review
  env:
    AI_REVIEW_PROVIDER: mock
    AI_REVIEW_FEEDBACK_MODE: artifact-only
    AI_REVIEW_OUTPUT_DIR: .ai-review
    AI_REVIEW_REPOSITORY_CONTEXT: "on"
  run: >
    python -m patchpatrol run
    --mode github-pr
    --provider mock
    --output-dir .ai-review

- name: Publish PatchPatrol summary
  if: always()
  run: |
    if [ -f .ai-review/ai-review.md ]; then
      cat .ai-review/ai-review.md >> "$GITHUB_STEP_SUMMARY"
    fi

Local branch diff:

AI_REVIEW_REPOSITORY_CONTEXT=on \
ai-review run --mode branch --base-ref origin/main --head-ref HEAD --provider mock

Local opt-out:

AI_REVIEW_REPOSITORY_CONTEXT=off \
ai-review run --mode working-tree --provider mock --output-dir .ai-review

Boundaries

PatchPatrol does not automatically ingest AGENTS.md, CONTRIBUTING.md, README files, architecture docs, tickets, comments, or prior artifacts as repository-aware rule input. Any future documentation ingestion would need a separate opt-in, allowlisted paths, and artifact-visible source attribution.

Persisted review memory is disabled for this milestone. PatchPatrol does not learn from prior accepted, dismissed, edited, or resolved findings.

Repo-local rules do not replace SAST, SCA, license scanning, merge approvals, or human review. They are prompt constraints for bounded PatchPatrol review, not deterministic policy gates.

Next step: Artifacts & schema