TenantAtlas/spec-candidates/383-baseline-subject-resolution-ui.md

# Spec Candidate 383 - Baseline Subject Resolution UI & Operator Decisions v1

## Candidate Status

Candidate for implementation after Specs 380, 381, and 382.

This candidate gives operators a focused UI to resolve real ambiguous baseline subjects, exclusions, unsupported foundation resources, and accepted limitations.

## Depends On

- Spec 380 - Provider Resource Identity & Binding Foundation v1
- Spec 381 - Baseline Matching Pipeline & Canonicalization v1
- Spec 382 - Baseline Compare Result Semantics & Gap Classification v1

## Spec Candidate Check

- **Problem**: Operators do not have a durable focused UI for resolving ambiguous baseline subjects, excluding non-governed subjects, accepting limitations, or revoking old decisions.
- **Today's failure**: Binding truth would exist after Spec 380, but without a safe operator surface, decisions remain ad hoc, hard to audit, and hard to reuse in future compares.
- **User-visible improvement**: Operators can resolve compare blockers from the Baseline Compare and OperationRun context with clear candidate details, required notes, RBAC, audit trail, and rerun guidance.
- **Smallest enterprise-capable version**: One focused resolution surface with create/update/revoke decisions, links from compare and OperationRun, minimal permissions, and audit events.
- **Explicit non-goals**: No generic Governance Inbox, no generic workflow engine, no approval workflow, no bulk auto-resolution beyond safe canonical built-ins, no customer-facing binding diagnostics, no restore UI changes.
- **Permanent complexity imported**: One Filament/operator surface, actions, capability gates, audit events, filtered links, UI tests, and decision-state rendering.
- **Why now**: After Specs 380-382, unresolved subjects become well-classified; operators need a safe place to make and revoke decisions that affect publication readiness.
- **Why not local**: Ad hoc table actions or manual DB changes would lack audit consistency, workspace/environment isolation, revocation semantics, and future compare reuse.
- **Approval class**: Workflow Compression.
- **Red flags triggered**: New UI surface and several action types. The defense is that the UI directly resolves an operator workflow blocker and uses existing binding/result truth instead of creating a broad workflow layer.
- **Score**: Nutzen: 2 | Dringlichkeit: 1 | Scope: 2 | Komplexitaet: 1 | Produktnaehe: 2 | Wiederverwendung: 2 | **Gesamt: 10/12**
- **Decision**: approve after Specs 380-382, with strict no-workflow-engine boundary and UI coverage decision required.

## UI Surface Impact

- **Reachable surface changed/added**: yes, a focused baseline subject resolution surface.
- **Page archetype**: operator resolution/workbench surface linked from Baseline Compare and OperationRun.
- **Design depth**: functional operator workflow design with table, detail drawer/page, explicit empty states, and dangerous-action confirmations where decisions hide blockers or revoke existing decisions.
- **Customer/operator safety**: operator-only; no raw provider IDs in customer-facing views. Truncated/masked provider identifiers may appear in operator technical detail where needed.
- **Dangerous/high-impact actions**: manual binding, exclusion, accepted limitation, unsupported marking, and revocation require authorization, operator note where applicable, audit, and confirmation when the action can affect customer-ready output.

## Proportionality Review

1. **Current operator problem**: Operators need to resolve real compare ambiguity and limitations before customer-ready review output can be trusted.
2. **Why existing structure is insufficient**: Baseline Compare detail and OperationRun follow-ups can point to issues but do not persist auditable decisions.
3. **Narrowest correct implementation**: Add one focused resolution surface over provider resource bindings; do not create a workflow engine.
4. **Ownership cost**: Filament page/resource ownership, RBAC/capabilities, action tests, browser/Filament smoke, and audit event maintenance.
5. **Rejected alternative**: Encoding decisions only in Baseline Profile was rejected because many decisions are subject/run/context-specific and need revocation history.
6. **Current-release truth or future prep**: Current-release operator workflow once Specs 380-382 establish trustworthy unresolved subject semantics.

## Problem

When TenantPilot detects ambiguous or unsupported baseline subjects, operators currently do not have a durable, focused way to decide:

- which candidate is the correct resource,
- whether the subject is non-governed/test/legacy,
- whether a foundation object is an accepted limitation,
- whether an old decision should be revoked,
- whether a compare needs rerun after resolution.

Without a UI, the binding model cannot be operationalized.

## Goal

Add a focused baseline subject resolution surface.

This is not a generic workflow engine. It is a bounded operator UI for creating, updating, and revoking provider resource bindings and resolution decisions.

## Scope

### In Scope

- Add "Resolve baseline subjects" surface.
- Link from Baseline Compare detail.
- Link from OperationRun follow-up where compare has unresolved subject blockers.
- Show ambiguous candidates.
- Allow manual binding to a candidate resource.
- Allow exclusion as non-governed.
- Allow accepted limitation.
- Allow unsupported coverage marking.
- Allow decision revocation.
- Require operator notes for manual decisions.
- Emit audit entries.
- Trigger or recommend rerun after decision.
- Add permissions/capabilities for resolution actions.

### Out of Scope

- Generic Governance Inbox.
- Generic workflow engine.
- Approval workflow.
- Bulk auto-resolution beyond safe canonical built-ins.
- Customer-facing binding diagnostics.
- Full historical backfill UI.
- Restore UI changes.

## Primary Surface

Suggested route/surface:

```text
Baseline Compare -> Resolve baseline subjects
```

Secondary entry points:

```text
OperationRun detail -> Resolve baseline subjects
Environment dashboard -> Attention card/link only
Baseline Profile -> Scope/exclusion policy entry point
```

## Table Columns

Resolution table should include:

```text
Subject
Subject class
Provider type
Problem
Candidate count
Current decision
Recommended action
Last seen
Action
```

## Detail Drawer / Page

For each unresolved subject, show:

```text
Baseline subject label
Canonical subject key
Subject class
Provider resource type
Problem reason
Current blocker category
Source compare run
Source operation run
Candidates
Existing binding if any
Audit history
Recommended action
```

## Candidate Fields

For each candidate:

```text
Display name
Provider resource type
Provider resource id truncated/masked
External id truncated/masked
Last inventory time
Source operation run
Source inventory item
Source policy version if available
Payload fingerprint/hash if available
Support capability
```

## Supported Actions

### Bind to this resource

Creates/updates active `provider_resource_bindings`.

Requires operator note.

### Exclude as non-governed

For test/legacy/pilot objects not part of the governed baseline.

Requires operator note.

### Accept limitation

For unsupported/foundation/inventory-only coverage where the product cannot yet compare the object but the limitation is acceptable.

Requires operator note.

### Mark unsupported

For resource classes outside current support scope.

Requires operator note unless registry marks unsupported by default.

### Resolve as provider built-in

Allowed when provider canonicalizer identifies a built-in/default with high confidence.

May be automatic or operator-confirmed depending confidence.

### Revoke decision

Supersedes/revokes active binding.

Requires operator note.

## Permissions

Introduce or reuse capabilities such as:

```text
baseline.subject_resolution.view
baseline.subject_resolution.manage
baseline.subject_resolution.revoke
baseline.subject_resolution.accept_limitation
baseline.subject_resolution.exclude
```

Only trusted workspace/environment operators should be allowed to create decisions that affect customer-ready output.

## OperationRun Integration

OperationRun should show actionable follow-up:

```text
Resolve 12 ambiguous baseline subjects before publication.
Accept or exclude 3 unsupported foundation subjects.
```

Follow-up links to the resolution surface with filters applied.

Resolved or accepted cases should not remain noisy action items.

## Baseline Profile Integration

Baseline Profile should own durable policy-level exclusions and accepted unsupported classes.

The resolution UI may create subject-level decisions.

Profile-level changes should be explicit, not accidental side effects.

## Audit Requirements

Every action records:

```text
who
when
action
old status
new status
subject
workspace
environment
provider
source compare
source operation run
operator note
```

## Acceptance Criteria

- Operators can resolve ambiguous tenant-owned subjects from Baseline Compare detail.
- Binding decisions persist and are used by future compares.
- Operators can exclude non-governed/test subjects with audit note.
- Operators can accept limitations with audit note.
- Operators can revoke previous decisions.
- OperationRun follow-up links to the focused resolution surface.
- Resolution UI distinguishes blocker, limitation, resolved, and excluded.
- No broad workflow engine is introduced.
- UI respects workspace/environment isolation and RBAC.

## Required Tests

- Feature test: resolution page lists unresolved ambiguous subjects.
- Feature test: bind candidate creates active binding.
- Feature test: future compare uses binding.
- Feature test: exclude non-governed creates audited decision.
- Feature test: accepted limitation no longer appears as unresolved blocker.
- Feature test: revoked decision no longer resolves future compare.
- Feature test: unauthorized user cannot create binding.
- Feature test: binding cannot be created across workspace boundary.
- Browser/Filament test: OperationRun follow-up opens filtered resolution page.
- Browser/Filament test: resolution states render correctly.

## Validation Commands

```bash
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Baselines
```

```bash
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament
```

Add focused tests for the resolution resource/page/actions.

## Risks

- Turning this into a generic workflow engine.
- Letting operators hide real drift with exclusions.
- Overloading Baseline Profile with per-run decisions.
- UI becoming too technical.
- Missing audit trail for customer-impacting decisions.

## Recommendation

Implement this fourth.

This candidate operationalizes the binding/resolution system after the core identity, matching, and result semantics are stable.