Reviewability Attestation

Overview

The platform should not grade prose. It should inspect whether the declared cargo matches the container: stated scope, actual diff, available evidence, and repository policy.

Problem AI reduces generation cost.

A contributor can create a large patch quickly. The maintainer still pays the cost of reconstructing intent, risk, and evidence.

Goal Admit reviewable changes.

The gate does not prove correctness. It decides whether the change is coherent enough for a human to inspect.

Constraint Legacy projects need degraded mode.

Missing tests or stale docs should not lock contributors out. False claims should.

Reviewability Attestation is not AI disclosure. It is accountable change control.

Admission flow

1Declare

Contributor states scope, tests, risks, and gaps.

2Analyze

Platform inspects files, symbols, CI, and policy.

3Compare

Claims are checked against observable facts.

4Route

The PR is admitted, warned, drafted, or quarantined.

5Improve

Missing evidence becomes a small maturity step.

Attestation model

The record separates facts the platform can verify from claims the contributor makes and evidence the repository does not have.

Verified Observed by the platform.

Commit range, changed files, sensitive paths, lockfiles, CI jobs, test results, and code owner areas.

Declared Stated by the contributor.

Problem statement, intended scope, non-goals, manual reproduction, risk assessment, and human acceptance.

Absent Known missing evidence.

No tests, flaky CI, stale docs, no owner map, no integration environment, or no reproduction path.

json

{
  "attestation_version": "0.1.0",
  "predicate_type": "https://reviewability.dev/attestation/v0.1",
  "subject": {
    "platform": "github",
    "repository": "example/project",
    "pull_request": 1234,
    "base_commit": "abc123",
    "head_commit": "def456"
  },
  "declared_intent": {
    "summary": "Fix parser crash on empty quoted field.",
    "scope": ["parser empty-field handling", "regression test"],
    "non_goals": ["No public API change", "No dependency changes"]
  },
  "verified_change_surface": {
    "files_changed": ["src/parser.rs", "tests/parser_empty_field.rs"],
    "sensitive_paths_touched": [],
    "dependency_files_changed": [],
    "public_api_changed": false
  },
  "evidence": {
    "verified": [{ "type": "ci_job", "name": "unit-tests", "status": "passed" }],
    "declared": [{ "type": "manual_reproduction", "claim": "Crash reproduced before patch." }],
    "absent": [{ "type": "integration_tests", "reason": "No suite exists." }]
  },
  "gate_decision": {
    "outcome": "admit",
    "reason": "Declared scope matches diff and available evidence."
  }
}

Gate outcomes and risk tiers

The controller has four outcomes. It should correct first, quarantine only when risk or contradiction requires it, and rarely reject permanently.

Outcome	Meaning	Maintainer impact
Admit	The record is coherent enough for normal review.	Enters the review queue.
Admit with warnings	The change is bounded, but evidence is incomplete or degraded.	Visible degraded-evidence label.
Hold as draft	The contributor can correct scope, test claims, or declarations.	No normal review notification.
Quarantine	The change is high-risk, unbounded, or unauthorized.	Requires explicit maintainer authorization.

Tier 1 Low risk

Markdown typo, CSS tweak, comment correction, dead link, small test-only change.

Tier 2 Medium risk

Helper refactor, localized bug fix, small parser change, non-breaking UI component.

Tier 3 High risk

Auth, crypto, lockfiles, build scripts, public APIs, migrations, sandboxing, permissions.

txt

Reviewability gate held this PR as draft.

Reason:
The attestation claims this is a UI-only change, but the diff modifies src/auth/session.rs.

Required correction:
Update the declared scope, split the PR, or link a maintainer-approved issue authorizing auth changes.

Repository policy

A repository-owned policy file defines sensitive paths, required evidence, degraded-mode behavior, draft conditions, and quarantine conditions.

yaml

version: "0.1"

default_mode: degraded_allowed

sensitive_paths:
  - path: "src/auth/**"
    tier: high
    requires:
      - linked_issue
      - maintainer_authorization
      - security_impact_statement
      - test_evidence_or_absence_declaration

  - path: "Cargo.lock"
    tier: high
    requires:
      - dependency_impact_statement
      - ci_evidence

  - path: ".github/workflows/**"
    tier: high
    requires:
      - maintainer_authorization
      - build_impact_statement

  - path: "docs/**"
    tier: low
    requires:
      - basic_intent

test_policy:
  allow_absent_tests_when_declared: true
  require_regression_test_for_bugfix_when_feasible: true
  flaky_ci_strategy: compare_base_branch

draft_on:
  - contradiction
  - missing_required_declaration
  - undeclared_dependency_change
  - scope_mismatch

quarantine_on:
  - high_risk_without_authorization
  - security_sensitive_scope_mismatch
  - undeclared_lockfile_change

Degraded mode Do not punish missing project infrastructure.

If tests do not exist, contributors can declare that absence. The gate routes the PR with warnings instead of inventing certainty.

Gentle ratchet Ask for one small improvement.

Add a regression test, fixture, reproduction script, command transcript, or manual verification note when feasible.

API and CLI surfaces

The system can start as a GitHub Action, GitLab CI job, or platform app. A platform-native version should expose submit, retrieve, evaluate, and authorize operations.

http

POST /repos/{owner}/{repo}/pulls/{number}/reviewability-attestations
GET  /repos/{owner}/{repo}/pulls/{number}/reviewability-attestations/latest
POST /repos/{owner}/{repo}/pulls/{number}/reviewability-evaluate
GET  /repos/{owner}/{repo}/pulls/{number}/reviewability-decision
POST /repos/{owner}/{repo}/pulls/{number}/reviewability-authorization

bash

reviewability init
reviewability attest \
  --pr 123 \
  --scope "parser crash fix" \
  --tests "cargo test parser_empty_field"
reviewability verify --pr 123
reviewability explain --pr 123

Reference components

Attestation collector

Receives structured records from PR forms, IDEs, agents, CI jobs, or CLI tools.

Diff analyzer

Computes changed files, sensitive areas, symbol changes, and dependency impact.

Evidence resolver

Maps test claims to CI jobs, static analysis, scans, and artifact evidence.

Policy engine

Applies repository policy and degraded-mode rules.

Contradiction engine

Compares claims against observable facts.

Gate controller

Routes the PR to admit, warning, draft, or quarantine.

Rollout path

Start with lightweight policy and labels. Move toward signed attestations, platform UI, and open standardization only after the workflow proves useful.

1Policy and labels

Classify files, sensitive paths, dependencies, and risk tiers.

2Basic schema

Require scope, tests, absent evidence, and acceptance.

3Contradictions

Compare claims to diff, CI, and policy.

4Degraded mode

Support flaky CI, missing tests, and stale documentation.

5Signed records

Bind attestations to commit range and PR identity.

txt

reviewability/admitted
reviewability/admitted-with-warnings
reviewability/held-draft
reviewability/quarantined
reviewability/degraded-evidence
reviewability/scope-mismatch
reviewability/dependency-impact
reviewability/high-risk

The durable standard is simple: a pull request should not be eligible for human review until it is reviewable by structure.

Make pull requests reviewable before they reach maintainers.

Overview

Admission flow

Attestation model

Gate outcomes and risk tiers

Repository policy

API and CLI surfaces

Reference components

Rollout path