TenantAtlas/specs/328-operations-hub-decision-first-workbench-productization/repo-truth-map.md

# Spec 328 Repo Truth Map

Status: implemented / validated
Created: 2026-05-18
Purpose: classify each Operations Hub decision-first workbench element before runtime implementation. This map is based on repository inspection only; implementation must update it before runtime changes if new source gaps appear.

## Classification Legend

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

## Required Data Areas

| Data area | Repo source | Preparation finding |
|---|---|---|
| Operations route | `apps/platform/routes/web.php`, route `admin.operations.index` | repo-real path is `/admin/workspaces/{workspace}/operations` |
| Operations page | `Operations` Filament page and `operations.blade.php` | repo-real current layout is decision-first workbench with secondary history table |
| OperationRun table | `OperationRunResource::table()` | repo-real status/outcome/type/timing table with filters, row URL, empty state |
| OperationRun detail | `TenantlessOperationRunViewer`, `OperationRunResource::infolist()` | repo-real detail/proof/diagnostic destination |
| OperationRun statuses | `OperationRunStatus` | repo-real `queued`, `running`, `completed` |
| OperationRun outcomes | `OperationRunOutcome` | repo-real `pending`, `succeeded`, `partially_succeeded`, `blocked`, `failed`; `cancelled` is reserved |
| OperationRun problem classes | `OperationRun::problemClass()`, scopes `activeStaleAttention()`, `terminalFollowUp()`, `dashboardNeedsFollowUp()` | repo-real for attention grouping without new priority engine |
| Summary counts | `summary_counts`, `OperationSummaryKeys`, `SummaryCountsNormalizer` | repo-real numeric keys and normalized rendering |
| Progress | `OperationRunProgressContract` | repo-real active-only progress semantics; terminal runs return `none` |
| Operation labels | `OperationCatalog::label()` | repo-real labels for canonical/legacy operation types |
| Environment relationship | `OperationRun::tenant()` relation to `ManagedEnvironment` | repo-real affected environment where present and accessible |
| Artifact/evidence links | `OperationRunLinks::related()`, `ArtifactTruthPresenter`, related resources | foundation-real/repo-real depending on operation type and linked artifact |
| Diagnostics | run detail technical sections, support diagnostics action, `failure_summary`, `context` | repo-real but default index must not expose raw data |
| RBAC | `OperationRunPolicy`, `OperationRunCapabilityResolver`, source policies/capabilities | repo-real membership, environment entitlement, capability checks |
| Workspace / Environment filter state | `WorkspaceContext`, `WorkspaceHubEnvironmentFilter`, `WorkspaceHubFilterStateResetter`, `CanonicalAdminEnvironmentFilterState`, filter chip partial | repo-real canonical `environment_id`, clear filter, alias rejection, cross-workspace guard |

## UI Element Map

| UI element | Source model/service/page | Status source | Authorization/capability | Workspace/Environment scope | OperationRun/evidence/artifact/audit link | Fallback/empty state | Classification |
|---|---|---|---|---|---|---|---|
| Operations Hub route | `admin.operations.index`, `OperationRunLinks::index()` | route + helper | workspace middleware and page access | current workspace route param | none | workspace chooser / 404 per existing middleware | repo-verified |
| Operations Hub title | `Operations` page/view | static copy to update | page access | workspace | none | static title | repo-verified |
| Workspace scope label | `OperateHubShell`, `WorkspaceContext` | current workspace/session | workspace membership | workspace shell | none | omit/404 if unavailable | repo-verified |
| Environment filter chip | `environmentFilterChip()`, shared chip partial | `WorkspaceHubEnvironmentFilter::fromRequest()` and table state | actor must access environment | `?environment_id={id}` only | none | no chip on clean URL | repo-verified |
| Clear filter action | `cleanWorkspaceHubUrl()`, shared resetter | generated clean route | page access | removes canonical filter/table state | none | omit when unfiltered | repo-verified |
| Legacy alias rejection | `WorkspaceHubFilterStateResetter`, navigation tests | forbidden query/session keys | page/source access | aliases do not set filter | none | workspace-wide view or safe 404 | repo-verified |
| Cross-workspace environment guard | `WorkspaceHubEnvironmentFilter::fromRequest()` | environment scoped by workspace and entitlement | workspace and environment entitlement | current workspace only | none | `abort(404)` / safe no-access | repo-verified |
| Main workbench question | `Operations::decisionWorkbench()` and `operations.blade.php` | static stable copy | page access | current scope | none | visible with no-attention state | repo-verified |
| Highest-priority operation | `Operations::selectedWorkbenchOperation()`, `OperationRun` problem class, outcome, status, freshness, timestamps | derived ordering from existing status/outcome/problem class | existing scoped Operations page query and OperationRun visibility | current workspace/filter | canonical detail link | `No operations need attention` | derived from existing model |
| Operation title/type | `OperationCatalog::label($run->type)` | type field | run visibility | current workspace/filter | detail link | fallback raw-safe type label | repo-verified |
| Outcome/status | `OperationRun.status`, `outcome`, badge renderer | status/outcome enums | run visibility | current workspace/filter | detail link | `Outcome unavailable` only if missing | repo-verified |
| Reason | problem class, lifecycle/freshness, outcome, `OperationUxPresenter`, `ReasonPresenter`, `failure_summary` summary where safe | derived from run truth | run/detail/source capabilities | current scope | detail link | `Reason unavailable` | derived from existing model |
| Impact | outcome, problem class, artifact truth, related artifact/review/restore context | derived from existing run/artifact truth | run/source capabilities | current scope | related links if authorized | `Impact unavailable` | derived from existing model |
| Environment | `OperationRun::tenant()` / `ManagedEnvironment` | managed environment relationship | entitlement via `OperationRunPolicy` / scope resolver | workspace and environment | related environment/resource links if existing | `Workspace-level operation` or unavailable | repo-verified |
| Timing | `created_at`, `started_at`, `completed_at`, `RunDurationInsights` | timestamps | run visibility | current scope | detail link | `Timing unavailable` | repo-verified |
| Proof/artifact state | `OperationRunLinks::related()`, `ArtifactTruthPresenter`, related resources | related route presence, artifact truth envelope | source policies/capabilities | current scope | artifact/evidence/review/backup/restore links | `Proof unavailable` or omit | foundation-real |
| Operation detail proof | `OperationRunLinks::tenantlessView()` | run id / route | `OperationRunPolicy` | current workspace/filter | canonical run detail | unavailable only if unauthorized | repo-verified |
| Progress state | `OperationRunProgressContract::forRun()` | summary counts/context/status | run visibility | current scope | detail link | no progress for terminal or unsupported | repo-verified |
| Determinate progress | `summary_counts.processed`, `summary_counts.total` | numeric trustworthy counts | run visibility | current scope | detail link | indeterminate/activity/unavailable | repo-verified |
| Terminal outcome guidance | `OperationRunResource::surfaceGuidance()`, `resolvePrimaryNextStep()`, `OperationUxPresenter` | status/outcome/problem class | run visibility | current scope | detail link/source links | generic review operation | foundation-real |
| Primary next action | `OperationRunLinks::tenantlessView()`, existing detail/source actions | route/action availability | run/source capability | current scope | operation detail link | unavailable when no selected operation | repo-verified for open operation; stronger proof links remain deferred to detail/source surfaces |
| Summary card: needs attention | `dashboardNeedsFollowUp()` / problem class scopes | stale active + terminal follow-up | scoped query | current workspace/filter | operations tab/deep link | 0 count with careful copy | repo-verified |
| Summary card: active operations | `status in queued/running` | status field | scoped query | current workspace/filter | active tab link | 0 count | repo-verified |
| Summary card: failed/blocked | completed failed/blocked outcomes | outcome field | scoped query | current workspace/filter | failed/follow-up tab link | 0 count | repo-verified |
| Summary card: follow-up required | terminal follow-up/problem class | problem class/outcome/reconciliation | scoped query | current workspace/filter | follow-up tab link | 0 count | repo-verified |
| Summary card: completed recently | completed_at within window | timestamp/outcome | scoped query | current workspace/filter | table filter/tab | 0 count | repo-verified |
| Summary card: artifact available | related artifact/evidence/link presence | related route / artifact truth | source capabilities | current workspace/filter | artifact/evidence links | unavailable if no safe aggregate | foundation-real |
| Right operation/proof panel | `operations.blade.php` over selected run payload | selected/highest run payload | run/source capabilities | current scope | operation detail link | no-attention/empty panel | repo-verified |
| Operations table/history | `OperationRunResource::table()` | table query, filters, row URL | run visibility | workspace + environment scoping | canonical detail route | existing `No operations found` | repo-verified |
| Tabs / problemClass links | `activeTab`, `problemClass`, `tabUrl()` | query/livewire state | page access | current scope | active/stale/follow-up/succeeded/partial/failed views | all tab default | repo-verified |
| Diagnostics disclosure | run detail technical sections, support diagnostics action | raw context/failure summary/support bundle | `SUPPORT_DIAGNOSTICS_VIEW` where action exposed | current scope | detail/support diagnostics only | collapsed/hidden | foundation-real |
| Raw provider payloads | raw Graph/provider payloads | not safe default | support-only future | N/A | N/A | never default-visible | deferred future capability |
| Retry/cancel/rerun action | existing detail/source actions only if present | action availability | source capability and confirmation | source scope | existing action owner | hidden/unavailable | foundation-real / deferred if unsupported |
| Platform-context tenant copy guard | runtime copy/tests | string assertions | N/A | page copy | N/A | use Workspace/Environment | repo-verified need; implementation test required |

## Required Runtime Element Decisions

| Element | v1 decision |
|---|---|
| Top summary-card rendering | native Filament `StatsOverviewWidget` / `Stat`; no custom Blade/Tailwind card component or explicit accent-bar system |
| New persisted operations workbench item | deferred future capability; do not build |
| New priority engine | deferred future capability; derive local ordering from existing status/outcome/problem class |
| New OperationRun status/outcome | deferred future capability; do not add |
| New summary-count keys | deferred future capability; do not add |
| AI operation summary | deferred future capability; do not show |
| Owner/due for operation | unavailable unless source operation context already proves it |
| Artifact/evidence where absent | explicit unavailable/missing state; do not invent |
| Green success state | allowed only for exact execution completion copy; never environment/governance health |
| Diagnostics | collapsed/hidden by default and capability-aware if exposed |
| Dangerous/mutating actions | do not add unless spec/plan updated first |
| Legacy query aliases | rejected/neutralized; do not support |

## Implementation Update Rule

If implementation discovers that a planned UI element has no safe source, no authorization path, or would require new persisted truth, the element must become `empty state / unavailable` or `deferred future capability`. Do not create backend foundation inside Spec 328 without updating `spec.md`, `plan.md`, and this map first.

## Implementation Close-Out

- Implemented the decision-first workbench on the existing `/admin/workspaces/{workspace}/operations` page.
- Selected-operation priority is derived locally from existing `OperationRun` status, outcome, problem class, timestamps, and scoped queries; no persisted priority engine was added.
- Determinate progress is delegated to `OperationRunProgressContract` and remains hidden for terminal outcomes.
- Primary next action is `OperationRunLinks::tenantlessView()` only; artifact/evidence/source-specific actions remain on existing detail/source surfaces.
- Summary cards are compact execution/attention signals backed by scoped OperationRun counts; they now render through the narrow native `OperationsWorkbenchStats` Filament `StatsOverviewWidget` using `Stat::make(...)`, descriptions, description icons, semantic colors, and disabled polling. No fake trends, sparklines, chart placeholders, custom Blade/Tailwind stat-card component, explicit custom accent bars, generic total-operation KPI, or average-duration KPI is used.
- `OperationsKpiHeader` remains available as existing widget code, but the Operations page no longer renders it above the workbench because the first viewport is owned by the decision-first summary cards.
- Diagnostics stay collapsed by default and raw provider/debug payloads are not default-visible.
- Clean workspace entry remains workspace-wide; `environment_id` remains the only accepted visible filter key.
- UI coverage registry files were not changed because the route and archetype remain the existing UI-003 Operations strategic surface; screenshots were stored under `artifacts/screenshots/`.