IRIS Regression Memory

IRIS Regression Memory is a deterministic review layer for behavior that is valid code but unsafe in context. It turns resolved production incidents into small, approved contracts and checks pull-request diffs for the exact failure mechanisms that caused them.

The repository is public-safe by design. Contracts contain issue keys, pull-request numbers, technical invariants, paths, and guard signals. They must not contain customer data, copied incident conversations, credentials, internal hostnames, or personal attribution.

Safety model

A finding is reported only when all of these are true:

1. The contract is approved.

2. The target repository matches the contract.

3. A changed production path matches the contract and is not excluded.

4. An added line contains an explicit violation_signal, matches an approved violation_line_pattern, one file contains every member of an approved violation_signal_group, or the diff removes an explicit removal_signal without a replacement.

Similarity, keywords outside the scoped paths, and retrieval rank cannot fail a review. A change with no applicable contract is inconclusive, never pass. Partial path coverage is displayed explicitly.

Related MCP server: Code Impact MCP

Run it

npm ci

# A GitHub pull request. Requires GITHUB_TOKEN, GH_TOKEN, or authenticated gh.
npm run assess -- --repo ignitetech-group/iris-sp-engines --pr 413

# A local unified diff.
npm run assess -- \
  --repo ignitetech-group/iris-sp-engines \
  --diff-file fixtures/replay/instagram-watermark-fix-reverse.diff

# Machine-readable integrations.
npm run assess -- --repo ignitetech-group/iris-sp-engines --diff-file change.diff --json
npm run assess -- --repo ignitetech-group/iris-sp-engines --diff-file change.diff --sarif

The CLI exits nonzero for detected regressions by default. Use --enforcement warning during rollout to keep findings advisory.

GitHub Action

name: Behavioral regression review
on:
  pull_request:

permissions:
  contents: read
  pull-requests: write
  checks: write

jobs:
  regression-memory:
    runs-on: ubuntu-latest
    steps:
      - uses: YOUR_ORG/iris-regression-memory@v0.3.0
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          enforcement: warning
          comment: "true"

The Action creates a sticky pull-request comment and a Check Run. In warning mode, a detected historical regression is neutral; in error mode it is a failure. Roll out in warning mode, measure precision, then protect the check only after contract owners approve enforcement.

If a fixture repository is reviewing changes on behalf of another codebase, set target_repository to the repository whose contracts should apply.

Local MCP server

Build and expose the same read-only assessment engine to an MCP client:

npm run build
node /absolute/path/to/iris-regression-memory/dist/mcp.cjs

Available tools are assess_diff, assess_pull_request, list_contracts, and get_contract. The server uses stdio, writes protocol messages only to stdout, and does not mutate repositories or contracts.

Outcomes

Every result also reports contract coverage as none, partial, or full over reviewable changed files.

Local evaluation

The v0.3.0 candidate was replayed against a 32-case local benchmark built from immutable Git history. It detected all 10 encoded culprit or reintroduction cases, passed all 10 safe applicable changes, correctly abstained on all 12 uncovered changes, and produced no false positives in this bounded set.

This is regression-suite evidence, not a claim of universal accuracy. See the benchmark guide and detailed evaluation report for methodology, per-case limitations, and reproduction instructions.

Repository map

contracts/schema.json          Contract validation schema
contracts/iris/*.yaml         Sanitized approved contracts
fixtures/positive/            Synthetic violations
fixtures/negative/            Safe changes
fixtures/replay/              Sanitized historical forward/reverse replays
src/                          Shared engine, CLI, Action, SARIF, and MCP adapters
docs/                         Architecture, evaluation, and authoring guidance
benchmarks/                    Immutable local historical PR benchmark manifest
reports/                       Public-safe local evaluation reports
tests/unit/                    Deterministic contract and replay tests

See docs/architecture.md, docs/contract-authoring.md, and docs/evaluation.md.