---
schema_version: 1
id: RAC-KV3SME4EYF2E
type: roadmap
tags: [validation, ci, onboarding, interop]
---
# RAC v0.15.2 — Validation Severity Overrides + SARIF Output

## Status

Planned

## Context

ADR-049 makes the write-time validation gate RAC's product, but two things keep
it from being adoptable in CI on a real repository. First, severities are fixed
in code, so a team pointing `rac validate` at a legacy corpus is failed on
hundreds of pre-existing findings at once — there is no warnings-first onramp.
Second, RAC emits only its JSON contract, which GitHub's PR surface does not
render, so findings are invisible where review happens.

This milestone delivers both, in RAC's idiom and without the custom-type
JSON-Schema registry ADR-052 deferred: a `validation` section in the committed
`.rac/config.yaml` for per-rule and per-type severity overrides (ADR-053), and a
`rac validate --sarif` output for GitHub Code Scanning (ADR-054).

## Outcomes

- A repository may downgrade or suppress findings — per rule code and per
  artifact type — via `.rac/config.yaml`, so CI can be green from day one and
  tightened over time. Default behaviour (no `validation` section) is unchanged.
- `rac validate <dir> --sarif` emits a deterministic, offline SARIF 2.1.0
  document covering core validation and OKF conformance findings.
- `review`, `watchkeeper`, and `portfolio` are unchanged; overrides scope to the
  `rac validate` entrypoints only.

## Initiatives

### Initiative 1 — Severity override model and loader

Add `rac.core.overrides` (the pure `SeverityOverrides` model, `resolve_severity`,
`apply_overrides`) and a `load_overrides` reader on `.rac/config.yaml` (reusing
the discovery walk extracted as `find_config_file`). Precedence: per-type ceiling
first, per-rule-code wins; `off` suppresses. Malformed shapes are a hard error.

### Initiative 2 — Thread overrides through validate

`validate_directory` loads the repository's overrides and applies them to each
file's findings and to OKF conformance (OKF findings gain a `severity`), before
status and exit code are computed. Single-file `rac validate` applies overrides
discovered from the file's directory. `validate_corpus` defaults to no overrides
so the repository model behind review/watchkeeper/portfolio is unchanged.

### Initiative 3 — SARIF output

Add `rac.output.sarif.render_validate_sarif` and a `--sarif` flag (mutually
exclusive with `--json`) emitting SARIF 2.1.0 for directory validation. Severity
maps to `level`; line to `region` when present; results sorted deterministically;
no timestamps. Single-file `--sarif` is a usage error.

### Initiative 4 — Coverage and docs

Unit tests (precedence, suppression, the YAML `off` coercion, malformed-config
errors), end-to-end `rac validate` tests (downgrade keeps CI green, rule beats
type ceiling, OKF finding downgradable), and SARIF structural + determinism
tests. Register the new test files in the CI battery (ADR-027). Document the
`validation` config section and `--sarif`; add a CHANGELOG entry.

## Constraints

- Additive (ADR-007): the directory `validate` JSON gains no breaking change; an
  absent `validation` section is a pure no-op; existing codes and exit semantics
  are unchanged when no overrides are declared.
- Determinism (ADR-002): overrides live in a committed file; SARIF is
  byte-identical for a given corpus state and build.
- ADR-052: no JSON-Schema custom-type registry, no `allOf`, no schema dependency.
- ADR-049: the default gate is not loosened; overrides are an explicit,
  committed, reviewable opt-in.

## Non-Goals

- A custom-type registry or repo-local schema files (ADR-052; deferred).
- Relationship-validation overrides or relationship SARIF (different report
  model; a later decision).
- A GitHub Action wrapper that uploads SARIF and annotates the PR (later work).
- Overrides influencing `review`/`watchkeeper`/`portfolio`.

## Implementation Contract

Pinned for v0.15.2.

### Behaviour

- `validation.rules` maps a rule code to `error|warning|off`; `validation.types`
  maps an artifact type to `error|warning`. Per-rule wins over the per-type
  ceiling; `off` suppresses. Unknown values raise `MalformedRepositoryConfig`.
- `rac validate <dir>` applies overrides before computing the exit code, so a
  downgraded type/rule keeps the run green. Single-file `rac validate` applies
  overrides from the file's directory.
- `rac validate <dir> --sarif` emits SARIF 2.1.0 (core + OKF findings),
  deterministic and offline; `--sarif` with a file or `-` is a usage error.

### Interface

- New `--sarif` flag on `validate`, mutually exclusive with `--json`. No other
  CLI surface change. `.rac/config.yaml` gains an optional `validation` section.

## Success Measures

- A corpus that fails `rac validate` by default exits 0 once a type or rule is
  downgraded in `.rac/config.yaml`, and the change is visible in the committed
  config.
- `rac validate rac/` is unchanged (the repo declares no overrides).
- `rac validate <fixture> --sarif` produces valid SARIF that re-renders
  byte-identically.

## Risks

- Teams could over-suppress and hollow out the gate. Mitigated: overrides are
  committed, reviewable, and shown in output; the default is the strict gate.
- SARIF is a second machine surface to keep stable. Mitigated: it is a thin
  derived projection with deterministic ordering and structural tests.

## Assumptions

- `.rac/config.yaml` (ADR-026) remains the repository config home.
- The five artifact types and their rule codes remain the validation surface;
  the per-type knob keys on any type string for forward compatibility.

## Related Decisions

- adr-053
- adr-054
- adr-052
- adr-049

## Related Requirements

- rac-cross-artifact-enforcement
- rac-growth-adoption

## Related Roadmaps

- v0.15.1-okf-conformance-check
