# Compact Causal Review Contract

The local orchestrator and same-user process are trusted to execute selected actors and submit their exact outputs. Reviewer and validator outputs remain semantically untrusted inputs: native code owns scope, risk, IDs, canonicalization, state, receipts, and gates, and rejects malformed or causally inconsistent results. The Git common-directory authority is the only authorization source; mirrors, bundles, summaries, and prose ledgers are untrusted data.

Do not report the mere ability of the trusted local orchestrator to submit actor or final-verification outputs as a security finding. Report concrete bypasses where untrusted repository content, malformed inputs, stale authority, path drift, or external callers can produce approval contrary to this boundary. Malicious same-user host/process authenticity is a non-goal because it can replace the extension or mutate local authority; external attestation requires a separately privileged signer or service and is not claimed.

## Ordinary facade

Use `gentle_review` as `start -> finalize -> validate` for every new ordinary review.

`start` derives the repository root, complete Git snapshot, untracked set, lineage, risk tier, selected lenses, original authored changed lines, and correction budget. The tier, scope, original lines, and budget never change after start.

Risk routing is deterministic:

| Tier | Route |
|---|---|
| `low` | Zero lenses; only proven docs/comments/format/typo-string work with no executable or configuration change |
| `medium` | One dominant lens for ordinary changes |
| `high` | Canonical 4R for auth, update, security, payments, data exposure/loss, permissions, shell/process, or more than 400 authored lines |

Generated files matching `testdata/golden/**` remain in snapshot identity but do not count as authored risk lines. Ordinary tests, fixtures, and snapshots are never broadly excluded. The correction budget is frozen as `min(200, ceil(original_changed_lines / 2))`.

`finalize` canonicalizes selected-lens results, assigns missing lens/finding IDs, and performs only the legal transition from the current compact state. The five states are `reviewing`, `correction_required`, `validating`, `approved`, and `escalated`.

`validate` loads the terminal receipt and authority, derives the named live Git gate, and runs with zero actors. It never mutates compact authority.

## Causal findings

Every finding supplies `evidence_class`, `causal_disposition`, and concrete proof. Concrete proof is one of `changed-hunk`, `candidate-created-path`, `differential-test`, or `before-after`.

| Field | Values |
|---|---|
| `severity` | `BLOCKER` \| `CRITICAL` \| `WARNING` \| `SUGGESTION` |
| `evidence_class` | `deterministic` \| `inferential` \| `insufficient` |
| `causal_disposition` | `introduced` \| `behavior-activated` \| `worsened` \| `pre-existing` \| `base-only` \| `unknown` |
| `proof_refs` | Prefixed concrete proof references |

Only severe `introduced`, `behavior-activated`, or `worsened` findings with valid proof can enter `correction_ids`. Deterministic candidate-caused blockers need no refuter. All inferential candidate-caused blockers use exactly one complete read-only refuter batch.

If native IDs are assigned to inferential findings, FINALIZE first returns canonical rows plus a content-derived request hash without mutation; completion requires identical lens input, that hash, and one complete refuter batch.

`pre-existing` and `base-only` findings become non-blocking follow-ups. `unknown`, insufficient evidence, malformed severe claims, missing/duplicate/extra refuter rows, and inconclusive severe outcomes escalate. `WARNING` and `SUGGESTION` remain informational.

Actor output cannot authorize transitions, corrections, receipts, gates, or delivery.

## Correction

Ordinary review permits one correction and one targeted validator.

Before editing, `finalize` requires a positive correction-line forecast. A forecast above the frozen budget escalates. After editing, the controller derives actual correction lines from Git and rejects an over-budget correction.

Correction remains bound to the original candidate tree, genesis paths, untracked set, and frozen correction IDs. It cannot add scope.

The targeted validator checks only the original criteria and one correction regression for the exact correction IDs. It cannot add findings, request another correction, launch actors, persist authority, or repeat. Later observations are inert follow-ups.

Final verification evidence is supplied and hashed only during finalization. Failure escalates and never reopens review.

## Authority and compatibility

Compact v2 stores one current state and terminal receipt under `<git-common-dir>/gentle-ai/reviews/compact-v2/<lineage>/`. Content-derived revisions, compare-and-swap replacement, exact retry idempotency, stale/semantic retry rejection, semantic validation, terminal immutability, atomic rename durability, and receipt readback are mandatory.

Existing graph-v1 ordinary lineages remain readable, gate-validatable, and exportable, but reject new mutation. Judgment Day remains mutable on graph-v1 until separately ported. Pre-graph numbered authority remains destructive-reset-only. Graph bundles never parse or import compact authority. Same-lineage graph-v1 and compact-v2 authority is ambiguous and fails closed until destructive reset quarantines both.

Mirrors remain non-authoritative and reconcile only after native allow.

## Lifecycle gates

Pre-commit, pre-push, pre-PR, and release validate an approved receipt against one exact typed command target with zero actors. Compact validation loads authority and receipt, derives live target/publication evidence, then immediately reloads authority and re-derives target/publication evidence before allow.

Pi additionally registers one one-shot authorization for the exact subsequent command. Bash-time target/publication derivation runs again. Repository identity, first-push destination, push destination, exact PR base, release evidence, protected-main release fast path, and fail-closed dangerous-command interception remain mandatory. Base advancement is unsupported without a receipt-bound signed CI trust root and therefore fails closed.

Release from protected `main` may bypass receipt validation only when the tag targets the current immutable `origin/main` SHA, required CI for that exact SHA is independently proven successful, the remote head is rechecked before tag push, and no fresh risk evidence exists. Major and post-incident releases require explicit extraordinary review.

Review transactions, validation, and SDD never commit, push, create a PR, release, or publish.

## Judgment Day

Judgment Day starts only when explicitly requested and replaces ordinary review for that lineage.

Judgment Day starts with exactly two blind judges and zero refuters.

Only Judgment Day may iterate, for at most two scoped fix/re-judgment rounds.

Findings surviving round two escalate; no third-round transition exists.

Judgment Day stays mutable on graph-v1 until separately ported.