Delimit Governance Framework (DGF)

Version: 0.1.0-rc (release candidate) Status: 15/15 breaking-change controls pass verify.py. CI gate met. Remaining for v0.1.0 tag: license finalization (CC-BY-4.0), move to dedicated delimit-ai/governance-framework repo, make dgf-verify wired into CI on consuming repos.

What this is

A machine-verifiable framework of governance controls for AI-assisted API development. Every control is numbered, citeable, and maps to a deterministic detector in the Delimit lint/diff engine. If a claim cannot be reproduced by running delimit lint or delimit diff on a public spec, it does not ship as a control.

This framework is intended to stand alongside CIS Controls, OWASP ASVS, and SLSA — enterprise compliance teams can cite DGF IDs directly in their internal policy documents.

License

CC-BY-4.0 (to be confirmed). Citeable in customer policy documents without restriction.

Control ID scheme

• DGF-BC-NNN — breaking change detection
• DGF-NB-NNN — non-breaking change classification
• DGF-PO-NNN — policy / lifecycle (deprecation, stability, versioning)
• DGF-SE-NNN — security-adjacent (auth scheme changes, scope removal)

Schema (each control file)

YAML frontmatter in a .md file under controls/:

---
id: DGF-BC-001
title: "Endpoint removal without major version bump"
severity: high
category: breaking_change
detector: diff_engine_v2.ChangeType.ENDPOINT_REMOVED
fixture: fixtures/DGF-BC-001/
semver_impact: MAJOR
introduced_in: 0.0.1
status: draft
---

# DGF-BC-001: Endpoint removal without major version bump

## Rule
Removing an endpoint (path + method combination) from a published API
is a MAJOR semver event. The diff engine emits `ENDPOINT_REMOVED`
which must block merge in strict policy mode.

## Why it matters
Existing clients calling the removed endpoint will receive 404s at
runtime. The caller cannot know the endpoint disappeared until a
request fails, at which point the blast radius is every consumer.

## How the detector works
...

## Reproducing the detection
```bash
delimit diff fixtures/DGF-BC-001/old.yaml fixtures/DGF-BC-001/new.yaml
# Expect: ENDPOINT_REMOVED change, severity=high, semver=MAJOR

## Release gate

`DGF v0.1.0` ships only when:

- [ ] Every control has a passing detector reference (non-empty `detector:` field pointing at a real engine symbol)
- [ ] Every control has a `fixtures/<control-id>/` directory with `old.yaml`, `new.yaml`, and `expected.json`
- [ ] CI runs `make dgf-verify` and all fixtures pass
- [ ] At least 15 breaking-change controls (`DGF-BC-001..015`)
- [ ] License finalized (CC-BY-4.0 default)
- [ ] Version tag `dgf-v0.1.0` on the framework repo

## v0.1.0-rc scope — 15 breaking-change controls

| ID | Title | Detector |
|---|---|---|
| DGF-BC-001 | Endpoint removal | `ENDPOINT_REMOVED` |
| DGF-BC-002 | Required param added | `REQUIRED_PARAM_ADDED` |
| DGF-BC-003 | Required response field removed | `FIELD_REMOVED` |
| DGF-BC-004 | Type changed | `TYPE_CHANGED` |
| DGF-BC-005 | Enum value removed | `ENUM_VALUE_REMOVED` |
| DGF-BC-006 | Request param type changed | `PARAM_TYPE_CHANGED` |
| DGF-BC-007 | Param flipped to required | `PARAM_REQUIRED_CHANGED` |
| DGF-BC-008 | Required body field added | `REQUIRED_FIELD_ADDED` |
| DGF-BC-009 | HTTP method removed | `METHOD_REMOVED` |
| DGF-BC-010 | Request param removed | `PARAM_REMOVED` |
| DGF-BC-011 | Security requirement removed | `SECURITY_REMOVED` |
| DGF-BC-012 | Field maxLength decreased | `MAX_LENGTH_DECREASED` |
| DGF-BC-013 | Field minLength increased | `MIN_LENGTH_INCREASED` |
| DGF-BC-014 | Response status code removed | `RESPONSE_REMOVED` |
| DGF-BC-015 | OAuth2 scope removed | `SECURITY_SCOPE_REMOVED` |

Every control has a passing fixture in `fixtures/<control-id>/` and maps
to a concrete detector in `core/diff_engine_v2.py`. Run `python
governance_framework/verify.py` to confirm 15/15 pass locally.

## Known engine gap

`ChangeType.FORMAT_CHANGED` is defined in the enum but not emitted by
the current diff engine. A future control (`DGF-BC-0NN format changed`)
will ship when the engine gap is closed. Tracked separately.

## How this fits the market position

The framework is the primary source of authority: anyone can reproduce
a control by running the engine against the fixture. Four principles:

1. Authority comes from reproducible tool output, not a person.
2. The framework is a public good (CC-BY-4.0), published under the
   `delimit-ai` org.
3. Audit reports reference DGF control IDs when documenting how the
   framework would have prevented a public API breakage.
4. Every audit is signed by the org, not a person.