.izri/scope.yml

.izri/scope.yml is the vocabulary the scope analyzer reasons against: what your modules are called, what kinds of change your PR types allow, and which paths deserve a second look.

It lives in your repository, at the PR head. That's the important part — it is checked in, code-reviewable, and versioned alongside the code it governs.

Resolution precedence

Four steps, in order:

#	Condition	Source
1	Valid .izri/scope.yml at the PR head	in_repo
2	Malformed .izri/scope.yml	falls back, and emits an info finding
3	No repo file, dashboard config exists	dashboard
4	Neither	defaults

In-repo wins on purpose. If the dashboard could override a checked-in file, the file in your repository would silently disagree with what actually ran — and the file is the thing your team reviews.

A malformed file degrades, it does not fail

A .izri/scope.yml that doesn't parse falls back to the dashboard config or defaults and emits an info-level finding saying so. Your build does not break because of a YAML typo.

The tradeoff: a broken config is easy to miss, because info findings don't block. If scope results look wrong, check the resolved source first — the delta report records which of the four cases applied.

Schema

Three top-level keys: modules, categories, sensitive.

modules:
  - name: billing
    paths:
      - src/billing/**
      - packages/payments/**
  - name: auth
    paths:
      - src/auth/**

categories:
  - label: feature
    expects:
      - src/**
    requires_test_change: true
  - label: docs
    forbids:
      - src/**
      - migrations/**
    requires_intent_statement: false

sensitive:
  - name: payment handling
    paths:
      - src/billing/charge.ts
  - name: migrations
    paths:
      - migrations/**

modules

Named groups of paths. This is the vocabulary findings are phrased in — without it, scope can only talk about file paths.

Field	Required	Type
name	yes	string
paths	yes	string[]

categories

What each kind of change is allowed to touch. label matches the PR's declared type, typically from its conventional-commit prefix.

Field	Required	Type	Effect
label	yes	string	The PR type this rule applies to.
expects	no	string[]	Paths this type normally touches.
forbids	no	string[]	Paths this type must not touch. Emits pr_type_forbidden_category at error — a hard rule that fails the umbrella.
requires_intent_statement	no	boolean	Require a body explaining the change.
requires_test_change	no	boolean	Require the diff to include test changes.

forbids is the only user-configurable hard gate. Everything else in scope is advisory. If you want a rule that genuinely blocks a merge, express it as forbids on a category — not as a sensitive path.

sensitive

Paths worth a human glance.

Field	Required	Type
name	yes	string
paths	yes	string[]

Touching one emits sensitive_path at info. It does not block, and it is not meant to — it points a reviewer at something. Teams reliably assume this gates a merge. It doesn't. Use forbids for that.

Auto-derivation

You don't have to write this by hand. Izri derives an initial config from your repository's file tree and metadata. The stored config records its origin:

Source	Meaning
derived	Generated by Izri.
user	Edited in the dashboard.
merged	Derived, then hand-adjusted.

Read the current one with the get_scope_config MCP tool, or from the dashboard. Export it to .izri/scope.yml when you want it under version control.

Worked example: a minimal config

Start here. Sensitive paths alone are useful before you formalize categories:

modules: []
categories: []
sensitive:
  - name: auth
    paths:
      - src/auth/**
  - name: migrations
    paths:
      - migrations/**

Worked example: enforcing a boundary

Stopping a docs PR from carrying a schema migration:

categories:
  - label: docs
    forbids:
      - migrations/**
      - src/**

A PR titled docs: update readme that also edits migrations/0042_add_column.sql now fails the umbrella, regardless of how clean every other signal is.

Related

• izri/scope — the signal this configures.
• Signals overview — severities and hard rules.