# Spec 336 Repo Truth Map

Status: implemented (runtime alignment completed)
Created: 2026-05-29
Purpose: classify each Baseline Compare Product Process Flow element before runtime implementation.

## Classification Legend

- `repo-verified`: exact runtime source exists and was inspected.
- `derived from existing model`: display value can be derived from existing persisted/domain truth.
- `foundation-real`: backend model/service exists, but exact page binding still needs implementation verification.
- `empty/unavailable state`: no safe source/action exists for v1; show explicit unavailable state or omit.
- `deferred future capability`: outside Spec 336 and must not be shown as live runtime truth.

## Required Data Areas

| Data area | Repo source | Preparation finding | Classification |
|---|---|---|---|
| Baseline Compare surface | `App\Filament\Pages\BaselineCompareLanding` + `filament.pages.baseline-compare-landing` | Environment-owned page with decision card + compare action; readiness flow now covers all repo-backed `BaselineCompareStats` states | repo-verified |
| Baseline assignment truth | `BaselineTenantAssignment` + relation to `BaselineProfile` | Missing assignment is a first-class state (`BaselineCompareStats.state = no_assignment`) | repo-verified |
| Baseline snapshot truth | `BaselineSnapshotTruthResolver::resolveCompareSnapshot()` | Snapshot “missing / building / incomplete / superseded / available” is repo-real via reason codes and lifecycle state | repo-verified |
| Environment snapshot / coverage proof | Latest inventory sync `OperationRunType::InventorySync` + `InventoryCoverage::fromContext(...)` + `InventoryItem` presence | There is repo truth for “coverage proof present” vs “missing/partial”; no explicit “stale” signal today | repo-verified |
| Compare run truth | `OperationRunType::BaselineCompare` (via `OperationCatalog::rawValuesForCanonical`) | `BaselineCompareStats` derives `idle/comparing/failed/ready` from latest run status/outcome | repo-verified |
| Decision output truth | Open drift findings (`Finding` with `finding_type=drift`, `source=baseline.compare`, scoped by baseline profile) + run outcome | “Decision output” is derived (findings present vs none, with caveats from coverage/evidence gaps) | derived from existing model |
| Evidence gap truth | `BaselineCompareStats::*ForRun(...)` reading latest run context/diagnostics | Evidence gaps are repo-real; they must remain separated from “operation proof” | repo-verified |
| OperationRun proof links | `OperationRunLinks::view(...)`, `OperationUxPresenter`, existing deep link helpers | Proof links are repo-real and already used by Baseline Compare | repo-verified |
| Baseline profile navigation | `BaselineProfileResource` | Baseline profile index exists and is capability-gated | repo-verified |
| Baseline snapshot navigation | `BaselineSnapshotResource` | Snapshot index exists and is workspace-scoped/capability-gated | repo-verified |
| Drift findings navigation | `FindingResource` + (optional) Baseline Compare Matrix | Findings index exists and is environment-scoped/capability-gated | repo-verified |
| “Generate evidence” action | N/A | No repo-real “compare evidence pack” generator is available as a Baseline Compare evidence artifact today | empty/unavailable state |

## State Family (Repo-Backed)

From `BaselineCompareStats::forTenant()`:

- `no_assignment`
- `no_snapshot`
- `invalid_scope`
- `idle` (inputs exist, run required)
- `comparing` (queued/running)
- `failed` (failed outcome)
- `ready` (completed + usable; findings may be 0 or >0, but coverage/evidence gaps may still require review)

## UI Element Map (Spec 336 Intended)

| UI element | Surface | Source model/service/page | Status source | Authorization/capability | Workspace/Environment scope | OperationRun/evidence link | Fallback/empty state | Classification |
|---|---|---|---|---|---|---|---|---|
| Decision card | Baseline Compare Landing | Expanded page view-model methods on `BaselineCompareLanding` | `BaselineCompareStats` + derived caveats | page access; links capability-gated | route-owned environment | links to baselines/findings/operation where allowed | “Compare unavailable” with truthful reason | repo-verified |
| Compare readiness flow (horizontal) | Baseline Compare Landing | `filament.components.product-process-flow-horizontal` | `BaselineCompareStats` + snapshot truth + coverage proof | page access; action visibility capability-gated | route-owned environment | step-level links only when repo-real | render `Unavailable` where truth is missing | repo-verified |
| Available inputs / proof panel | Baseline Compare Landing | repo-backed inputs only | snapshot/run/inventory proof state | capability-gated deep links | route-owned environment + workspace scope for baseline artifacts | operation proof link + evidence gap summary | explicit “Unavailable” states | repo-verified |
| Drift summary | Baseline Compare Landing | `Finding` severity counts + attention counts | derived from findings + run outcome | finding visibility policy | route-owned environment | link to findings only when authorized | “Drift result unavailable” | repo-verified |
| Evidence/coverage state | Baseline Compare Landing | `coverageStatus`, `uncoveredTypes`, `evidenceGaps*` from stats | run-derived caveats | page access; support/raw remains gated | route-owned environment | separate from operation proof | visible warnings before diagnostics | repo-verified |
| Diagnostics disclosure | Baseline Compare Landing | `baselineCompareDiagnostics` + evidence gap diagnostics | disclosure label only by default | collapsed and capability-aware | route-owned environment | optional deep link to run | “Diagnostics - Collapsed” even when present | repo-verified |

## Explicit Non-Truth / Deferred Claims

| Claim | v1 decision |
|---|---|
| “Environment is healthy/compliant/protected/customer-safe” | deferred future capability; must not be shown |
| “Evidence package exists” | empty/unavailable until a repo-real artifact exists and is linked |
| “Stale” snapshot semantics | only allowed if a repo-real staleness signal exists; otherwise render as `Unavailable` or omit |