# ADR-0067: OSHUN Trust, Confidence, And Provenance Badge UI Behavior

- Status: Accepted
- Date: 2026-03-24

## Context

OSHUN already exposed confidence scores, trust-oriented labels, provenance copy,
and watermarking concepts across Veritas and Studio, but those signals were not
governed by one shared visual contract:

- Veritas home claims and queue rows used local confidence pills with no shared
  provenance grammar
- provenance-review and watermark-governance workspaces relied on descriptive
  copy rather than consistent badge states
- the shell had no explicit rule preventing provenance badges from being read as
  truth or high-confidence badges

The V1 TODO list explicitly requires the visual rules for
trust/confidence/provenance badges to be defined, and the shell PRD requires
trust-bearing UI to remain readable, explicit, and non-misleading.

## Decision

Publish one canonical trust-signal behavior contract from
`libs/oshun/design-tokens/src/tokens.ts` and make the web shell consume it
through tokenized CSS variables, trust helpers, Studio inspection surfaces,
representative Veritas trust-bearing UI, and representative provenance and
watermark operator workspaces.

The shell contract is:

1. Separate judgement from lineage
   - confidence badges describe how strong a reading is, while provenance badges
     describe whether origin or source lineage is inspectable

2. Explicit confidence qualifiers
   - numeric scores always pair with high, medium, or low confidence language
     instead of a bare percentage

3. Inspectable provenance
   - provenance badges imply a visible trail, review path, or watermark record
     available from the surrounding surface

4. Restrained semantic framing
   - even high-confidence states use translucent semantic treatment rather than
     success-banner styling

5. Honest missing-state language
   - partial or missing provenance must be labeled explicitly rather than buried
     as neutral metadata

## Consequences

- `oshun-v1-foundation` now includes a trust-signal behavior contract in
  addition to the existing core, domain-accent, grounded-evidence, and
  disclosure contracts.
- `apps/oshun/web/src/design-system/globals-v2.css` now defines shared
  confidence/provenance tones plus summary-strip, inline-badge, and metric-pill
  variables.
- `apps/oshun/web/src/design-system/trust-signals.ts` now provides the canonical
  web helper layer for confidence thresholds, readable labels, and trust-signal
  summary composition.
- Studio design-language tooling can now inspect confidence states, provenance
  states, and trust badge role rules as first-class governed artifacts.
- Veritas trust-bearing surfaces plus representative provenance and watermark
  workspaces now consume one shell grammar instead of styling trust indicators
  locally or leaving provenance implicit.

## Implementation

- Shared contract:
  - `libs/oshun/design-tokens/src/tokens.ts`
  - `libs/oshun/design-tokens/src/tokens.test.ts`
- Web adapter and CSS:
  - `apps/oshun/web/src/design-system/tokens.ts`
  - `apps/oshun/web/src/design-system/index.ts`
  - `apps/oshun/web/src/design-system/trust-signals.ts`
  - `apps/oshun/web/src/design-system/globals-v2.css`
  - `apps/oshun/web/src/design-system/__tests__/tokens.test.ts`
  - `apps/oshun/web/src/design-system/__tests__/trust-signals.test.ts`
- Web trust-bearing surfaces:
  - `apps/oshun/web/src/components/domains/VeritasSurface.tsx`
  - `apps/oshun/web/src/components/domains/veritas/VeritasReadingQueue.tsx`
  - `apps/oshun/web/src/components/studio/StudioIsisProvenanceTrackingWorkspace.tsx`
  - `apps/oshun/web/src/components/studio/StudioAjaContentWatermarkingWorkspace.tsx`
- Studio inspection and browser verification:
  - `apps/oshun/web/src/components/studio/StudioDesignLanguageWorkspace.tsx`
  - `apps/oshun/web/src/components/__tests__/StudioDesignLanguageWorkspace.test.tsx`
  - `apps/oshun/web/e2e/studio-design-language-smoke.spec.ts`
  - `apps/oshun/web/e2e/studio-isis-provenance-tracking-smoke.spec.ts`
  - `apps/oshun/web/e2e/studio-aja-content-watermarking-smoke.spec.ts`
  - `apps/oshun/web/e2e/veritas-full-journey.spec.ts`

## Verification

This slice is complete when:

1. shared design-token tests pass
2. targeted web trust-helper, Veritas, and Studio tests pass
3. targeted eslint passes for the changed shared, web, and e2e files
4. Playwright verifies Studio trust governance plus live Veritas and
   provenance/watermark surfaces