# CaveatDiff v0.1 specification

Status: accepted for implementation on 2026-08-25.

## Goal

Make material model-card disclosure changes easy to review without using an
LLM or sending unpublished documentation to a server.

## First vertical slice

Given a baseline and current Markdown model card, the engine must:

1. Parse headings and group common synonyms into disclosure categories:
   limitations, risks and bias, intended use, out-of-scope use, training data,
   and evaluation.
2. Parse a safe subset of Hugging Face YAML front matter and compare `license`,
   `base_model`, `datasets`, `language`, and `pipeline_tag`.
3. Report removed disclosure sections and removed non-empty statements within
   limitations, risk, bias, and out-of-scope sections.
4. Report added and changed evaluation numbers without deciding whether higher
   or lower is better.
5. Report removed URLs from disclosure sections.
6. Produce deterministic text and `caveatdiff.report.v1` JSON output.

## Verdicts

- `disclosure-review`: a disclosure section, risk statement, relevant URL, or
  license/dataset declaration was removed or changed.
- `material-change`: structured metadata or evaluation numbers changed without
  a disclosure removal.
- `stable`: no monitored material change was found.

## Safety and privacy

- Browser processing only; no analytics, storage, cookies, or network calls.
- Node CLI has no runtime dependencies or network access.
- Markdown is treated only as text. It is never rendered as executable HTML.
- YAML tags, anchors, objects, and arbitrary nesting are unsupported and never
  evaluated.
- Each input is limited to two million characters.
- Results are review signals, not an assessment of model quality or safety.

## Accessibility

- Native controls, complete keyboard operation, visible focus, and text status.
- Results use headings, lists, and captioned scrollable tables.
- No color-only meaning and a single-column narrow layout.
- Results summary receives focus and is announced after analysis.

## Delivery

- MIT license.
- Independent public GitHub repository.
- GitHub Pages live app.
- Node 20+ test matrix and GitHub Action for repository model-card changes.