<!--
                █████
               ░░███
       ██████  ███████    ██████
      ███░░███░░░███░    ░░░░░███
     ░███ ░███  ░███      ███████
     ░███ ░███  ░███ ███ ███░░███
     ░░██████   ░░█████ ░░████████
      ░░░░░░     ░░░░░   ░░░░░░░░

   Copyright (C) 2026 — 2026, Ota. All Rights Reserved.

   DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

   Licensed under the Apache License, Version 2.0. See LICENSE for the full license text.
   You may not use this file except in compliance with that License.
   Unless required by applicable law or agreed to in writing, software distributed under the
   License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
   either express or implied. See the License for the specific language governing permissions
   and limitations under the License.

   If you need additional information or have any questions, please email: os@ota.run
-->

# Audit and Provenance

This document defines the V5 target for audit-friendly machine output and provenance semantics in ota.

The goal is to make org policy, templates, and repo readiness explainable after the fact without guessing where the result came from.

## Purpose

Audit and provenance support:

- compliance review
- org policy enforcement
- reproducible diagnosis
- agent-safe decision tracing
- trust in inferred vs declared values

## Core principles

- declared contract state remains the source of truth
- derived output must stay clearly derived
- provenance must be visible for inferred or policy-derived values
- audit data should be stable and machine-readable
- mutation paths should leave an observable trail

## Provenance model

The current shipped output already uses per-field provenance in detection and additive provenance
labels on diagnosis findings and explain steps.
V5 extends that idea to org policy and template-derived behavior.

Current shipped detect comparison output also carries stable ownership/provenance labels for
existing-contract review, and add/update entries include direct detector source and confidence so
automation does not need to reconstruct that evidence from separate arrays. On that detect
comparison surface, `provenance` remains the shipped stable label `repo_signals`, with
`provenance_key` available alongside it for the same machine-oriented classification. Detect
comparison entries also expose `owner_kind`:

- `detected` for add candidates that are not yet in the contract
- `manual` for existing fields that are hand-authored or explicitly pinned
- `merged` for fields that ota previously wrote and recorded under
  `metadata.ota.detect.field_ownership`
- `policy` reserved for future machine-owned policy-backed contract surfaces
- `metadata.ota.detect` is ota-reserved and must remain a mapping when detect ownership tracking is in use

Normal drift surfaces only treat `merged` fields as detector-owned drift. Rewrite preview remains
broader: it can still show `manual` removals because a full replacement would drop them.

`ota init --json` now exposes a per-field `provenance` array for the starter contract itself:

- `detector-inferred` fields point back to repo evidence with `source` and `confidence`
- `template-derived` fields identify starter-only defaults such as version pinning, task notes,
  and generated `agent` guidance

`ota workspace init --json` and `ota workspace detect --json` now expose the same style of
per-field `provenance` array for the generated workspace scaffold:

- `workspace-derived` fields point back to the workspace root or workspace discovery
- `workspace-declared` fields mark values preserved from an existing `ota.workspace.yaml`
- `template-derived` fields identify scaffold defaults such as starter versioning and the default
  `required: true` repo entries

The intended provenance categories are:

- repo-declared
- policy-derived
- template-derived
- detector-inferred
- workspace-derived
- workspace-declared
- user-mutated

Policy-backed provisioning now uses the same provenance idea on diagnosis: the repo declares what
it needs, policy declares where it may come from, doctor/explain report that provenance, and the
receipt records which approved source won.

## Signed config direction

Signed config is an optional trust mechanism for environments that need stronger integrity guarantees.

The target behavior is:

- signed `ota.yaml` can be recognized as trusted source material
- unsigned or altered files remain valid unless policy says otherwise
- signatures do not replace validation or diagnosis
- signing is an additive trust layer, not a separate contract format

## Audit output expectations

Audit-friendly output should answer:

- what was declared
- what was inferred
- what was derived from policy
- what was changed
- why a command considered the result ready or not ready

## Scope

Audit/provenance is for:

- explainable diagnosis
- reviewable detection output
- policy pack traceability
- template application traceability

It is not for:

- hidden mutation logging
- a general audit database
- approval workflow orchestration
- replacing the contract with runtime state
- hosted control plane operations
- fleet-wide reporting or retention policy