Disciplines · Decisions (ADRs)

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

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:

5sections3 minread
Markdown source
On this page
  • 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