TenantAtlas/specs/222-findings-intake-team-queue/plan.md

# Implementation Plan: Findings Intake & Team Queue V1

**Branch**: `222-findings-intake-team-queue` | **Date**: 2026-04-21 | **Spec**: `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/222-findings-intake-team-queue/spec.md`
**Input**: Feature specification from `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/222-findings-intake-team-queue/spec.md`

**Note**: This plan keeps the work inside the existing admin workspace shell, tenant-owned `Finding` truth, current tenant finding detail surface, and the already-shipped `My Findings` destination from Spec 221. The intended implementation is one new canonical `/admin` page plus one narrow self-claim shortcut. It does not add persistence, a team model, a second permission family, bulk claim, queue automation, or provider-side work.

## Summary

Add one canonical admin-plane intake queue at `/admin/findings/intake` that shows visible unassigned findings across the current workspace, separates `Unassigned` from the stricter `Needs triage` subset, and lets an authorized operator claim an item into the existing `/admin/findings/my-work` surface through a lightweight preview/confirmation flow without opening the broader assignment form first. Reuse the existing `MyFindingsInbox` page shape, `FindingResource` badge and navigation helpers, `CanonicalAdminTenantFilterState` for active-tenant prefiltering, `CanonicalNavigationContext` for intake-to-detail continuity, and `FindingWorkflowService` plus the current `finding.assigned` audit path, while adding one claim-specific stale-row guard so a delayed click cannot silently overwrite another operator's successful claim.

## Technical Context

**Language/Version**: PHP 8.4.15, Laravel 12, Filament v5, Livewire v4, Blade  
**Primary Dependencies**: Filament admin pages/tables/actions/notifications, `Finding`, `FindingResource`, `FindingWorkflowService`, `FindingPolicy`, `CapabilityResolver`, `CanonicalAdminTenantFilterState`, `CanonicalNavigationContext`, `WorkspaceContext`, and `UiEnforcement`  
**Storage**: PostgreSQL via existing `findings`, `tenants`, `tenant_memberships`, `audit_logs`, and workspace session context; no schema changes planned  
**Testing**: Pest v4 feature tests with Livewire/Filament assertions; existing action-surface and Filament guard suites remain ambient CI protection  
**Validation Lanes**: fast-feedback, confidence
**Target Platform**: Dockerized Laravel web application via Sail locally and Linux containers in deployment  
**Project Type**: Laravel monolith inside the `wt-plattform` monorepo  
**Performance Goals**: Keep intake rendering and claim DB-only, eager-load tenant and owner display context, avoid N+1 capability lookups across visible tenants, and keep first operator scan within the 10-second acceptance target  
**Constraints**: No Graph calls, no new `OperationRun`, no new capabilities, no new persistence, no hidden-tenant leakage, no bulk claim, no new assets, no silent overwrite on stale claim attempts, and no expansion of lifecycle or ownership semantics  
**Scale/Scope**: One admin page and Blade view, one derived intake query, one narrow workflow-service extension or guard for claim conflict handling, three focused feature suites, and ambient compliance with existing action-surface and Filament table guards

## UI / Surface Guardrail Plan

- **Guardrail scope**: changed surfaces
- **Native vs custom classification summary**: native Filament page, table, tab, badge, row-action, notification, and empty-state primitives only
- **Shared-family relevance**: findings workflow family and canonical admin findings pages
- **State layers in scope**: shell, page, detail, URL-query
- **Handling modes by drift class or surface**: review-mandatory
- **Repository-signal treatment**: review-mandatory
- **Special surface test profiles**: global-context-shell
- **Required tests or manual smoke**: functional-core, state-contract
- **Exception path and spread control**: none; the queue stays list-first with one safe inline shortcut while dangerous lifecycle actions remain on existing tenant detail and tenant findings list surfaces
- **Active feature PR close-out entry**: Guardrail

## Constitution Check

*GATE: Passed before Phase 0 research. Re-check after Phase 1 design.*

| Principle | Pre-Research | Post-Design | Notes |
|-----------|--------------|-------------|-------|
| Inventory-first / snapshots-second | PASS | PASS | The queue remains a live derived view over `Finding` truth only; no snapshot or backup semantics are introduced |
| Read/write separation | PASS | PASS | The only write is the narrow `Claim` assignment shortcut; it uses a lightweight preview and explicit confirmation step, is TenantPilot-only, audit-logged, race-checked, and covered by focused tests while dangerous workflow mutations remain on existing tenant detail surfaces |
| Graph contract path | PASS | PASS | No Graph client, contract-registry, or provider API work is added |
| Deterministic capabilities / RBAC-UX | PASS | PASS | Workspace membership plus at least one currently viewable findings scope gates the admin page, per-tenant findings visibility gates rows and counts once inside the queue, `TENANT_FINDINGS_ASSIGN` gates claim, non-members stay `404`, workspace members with no currently viewable findings scope get `403`, and in-scope members missing claim capability remain `403` on execution |
| Workspace / tenant isolation | PASS | PASS | The admin queue is workspace-scoped, row disclosure remains tenant-entitlement checked, and drilldown stays on `/admin/t/{tenant}/findings/{finding}` with tenant-safe continuity |
| Run observability / Ops-UX | PASS | PASS | No long-running work, no `OperationRun`, and no queue/progress surface changes are introduced; the short DB-only claim write is audit-logged |
| Proportionality / no premature abstraction | PASS | PASS | The intake query stays page-local and the claim behavior extends existing workflow seams instead of creating a new queue framework or team-routing abstraction |
| Persisted truth / few layers | PASS | PASS | Intake views, queue reason, and summary counts remain derived from existing finding status, assignee, owner, due-date, and entitlement truth |
| Behavioral state discipline | PASS | PASS | `Unassigned` and `Needs triage` remain derived queue views; no new persisted status, reason family, or ownership role is introduced |
| Badge semantics (BADGE-001) | PASS | PASS | Severity and lifecycle cues reuse existing findings badge rendering and due-attention helpers |
| Filament-native UI (UI-FIL-001) | PASS | PASS | The design stays within Filament page, table, tabs, row actions, notifications, and empty-state primitives |
| Action surface / inspect model | PASS | PASS | Row click remains the primary inspect model, `Claim` is the only inline safe shortcut, and there is no redundant `View` or bulk action lane |
| Decision-first / OPSURF | PASS | PASS | The intake queue is the primary decision surface for pre-assignment routing and keeps diagnostics secondary behind finding detail |
| Test governance (TEST-GOV-001) | PASS | PASS | Proof remains in three focused feature suites with explicit lane fit and no new heavy-governance or browser family |
| Filament v5 / Livewire v4 compliance | PASS | PASS | The feature remains inside Filament v5 patterns and Livewire v4-compatible page/table behavior only |
| Provider registration / global search / assets | PASS | PASS | Panel providers already live in `apps/platform/bootstrap/providers.php`; the new page only extends `AdminPanelProvider`, `FindingResource` global search is unchanged and already has a View page, and no new assets are introduced so the deploy `filament:assets` step is unchanged |

## Test Governance Check

- **Test purpose / classification by changed surface**: `Feature` for the admin intake page, authorization boundaries, and claim handoff behavior
- **Affected validation lanes**: `fast-feedback`, `confidence`
- **Why this lane mix is the narrowest sufficient proof**: The feature risk is visible queue truth, tenant-safe filtering, `Needs triage` subset semantics, claim authorization, stale-row conflict handling, and handoff into an existing personal queue. Focused feature tests prove that integrated behavior without adding unit seams, browser coverage, or heavy-governance breadth.
- **Narrowest proving command(s)**:
  - `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Findings/FindingsIntakeQueueTest.php tests/Feature/Authorization/FindingsIntakeAuthorizationTest.php`
  - `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Findings/FindingsClaimHandoffTest.php`
- **Fixture / helper / factory / seed / context cost risks**: Moderate. The tests need one workspace, multiple visible and hidden tenants, owner-versus-assignee combinations, unassigned and assigned findings across open and terminal states, explicit active-tenant session context, and one stale-claim race scenario.
- **Expensive defaults or shared helper growth introduced?**: no; the new suites should reuse `createUserWithTenant(...)` and `Finding::factory()` and keep any intake-specific helper local to the new tests
- **Heavy-family additions, promotions, or visibility changes**: none
- **Surface-class relief / special coverage rule**: named special profile `global-context-shell` is required because the page depends on workspace context, active-tenant prefilter continuity, tenant-safe detail drilldown, and row-level capability visibility
- **Closing validation and reviewer handoff**: Reviewers should rely on the exact commands above and verify that hidden-tenant or capability-blocked findings never leak into rows, counts, tab badges, or tenant filter values; `acknowledged` findings stay out of intake; `Needs triage` remains limited to `new` and `reopened`; claim leaves owner and workflow status unchanged; and stale claims fail honestly instead of overwriting another operator's assignment.
- **Budget / baseline / trend follow-up**: none
- **Review-stop questions**: Did the intake query accidentally include assigned or `acknowledged` rows? Did claim mutate owner or lifecycle state? Did a second inline action or bulk lane appear? Did any new shared queue abstraction or team model appear without a second real consumer? Did stale-claim behavior degrade into silent overwrite?
- **Escalation path**: document-in-feature unless a second shared intake surface or reusable cross-tenant queue framework is introduced, in which case follow-up-spec or split
- **Active feature PR close-out entry**: Guardrail
- **Why no dedicated follow-up spec is needed**: The feature remains bounded to one derived queue surface and one narrow claim path, with no new persistence, no new workflow family, and no structural test-cost center

## Project Structure

### Documentation (this feature)

```text
specs/222-findings-intake-team-queue/
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── contracts/
│   └── findings-intake-team-queue.logical.openapi.yaml
├── checklists/
│   └── requirements.md
└── tasks.md
```

### Source Code (repository root)

```text
apps/platform/
├── app/
│   ├── Filament/
│   │   ├── Pages/
│   │   │   └── Findings/
│   │   │       └── FindingsIntakeQueue.php
│   │   └── Resources/
│   │       └── FindingResource.php
│   ├── Providers/
│   │   └── Filament/
│   │       └── AdminPanelProvider.php
│   └── Services/
│       └── Findings/
│           └── FindingWorkflowService.php
├── resources/
│   └── views/
│       └── filament/
│           └── pages/
│               └── findings/
│                   └── findings-intake-queue.blade.php
└── tests/
    └── Feature/
        ├── Authorization/
        │   └── FindingsIntakeAuthorizationTest.php
        └── Findings/
            ├── FindingsClaimHandoffTest.php
            └── FindingsIntakeQueueTest.php
```

**Structure Decision**: Standard Laravel monolith. The feature stays inside the existing admin panel provider, finding domain model, workflow service, and focused Pest feature suites. No new base directory, package, or persisted model is required.

## Complexity Tracking

| Violation | Why Needed | Simpler Alternative Rejected Because |
|-----------|------------|-------------------------------------|
| none | — | — |

## Proportionality Review

- **Current operator problem**: Unassigned findings exist in the current workflow, but there is no single trustworthy workspace-safe queue for the pre-assignment backlog.
- **Existing structure is insufficient because**: Tenant-local findings lists and ad hoc filters still force tenant hopping and do not provide a clean handoff from shared backlog into the existing personal queue.
- **Narrowest correct implementation**: Add one admin intake page and one safe self-claim shortcut derived directly from existing finding lifecycle, due-state, ownership, and entitlement truth.
- **Ownership cost created**: One page/view pair, one small claim conflict guard inside the existing workflow service seam, and three focused feature suites.
- **Alternative intentionally rejected**: A broader team workboard, notification-first routing model, or queue framework was rejected because those shapes add durable workflow machinery before this smaller intake slice is proven useful.
- **Release truth**: Current-release truth. The work operationalizes an already-existing unassigned backlog now rather than preparing a later team-orchestration system.

## Phase 0 Research

Research outcomes are captured in `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/222-findings-intake-team-queue/research.md`.

Key decisions:

- Implement the intake queue as a new Filament admin page with slug `findings/intake` under the existing `AdminPanelProvider`, not as a tenant resource variant and not as a standalone controller route.
- Keep queue truth as a direct `Finding` query scoped by workspace, visible tenant IDs, `assignee_user_id IS NULL`, and `Finding::openStatuses()` rather than `Finding::openStatusesForQuery()`, because `acknowledged` rows are intentionally excluded from intake.
- Model `Unassigned` and `Needs triage` as fixed queue views inside the page shell, not as a new taxonomy, persisted preference, or generic filter framework.
- Reuse `CanonicalAdminTenantFilterState` for the active-tenant prefilter and `CanonicalNavigationContext` for intake-to-detail continuity and `Back to findings intake` behavior.
- Add `Claim finding` as a narrow row action that reuses the existing findings assign capability, success notification patterns, lightweight preview/confirmation content, and `finding.assigned` audit trail, but adds a claim-specific stale-row guard so delayed clicks fail honestly when another operator claimed the row first.
- Prove the feature with three focused Pest feature suites while relying on existing action-surface and Filament-table guards as ambient CI coverage.

## Phase 1 Design

Design artifacts are created under `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/222-findings-intake-team-queue/`:

- `research.md`: routing, query, fixed-view, claim, and continuity decisions
- `data-model.md`: existing entities plus derived intake row, queue state, and claim outcome projections
- `contracts/findings-intake-team-queue.logical.openapi.yaml`: internal logical contract for intake rendering, claim, and continuity inputs
- `quickstart.md`: focused validation workflow for implementation and review

Design decisions:

- No schema migration is required; the queue, view counts, and empty states remain fully derived.
- The canonical implementation seam is one new admin page plus one narrow workflow-service claim guard and lightweight preview/confirmation surface, not a new shared queue or team-routing subsystem.
- Active tenant context remains canonical through `CanonicalAdminTenantFilterState`, while detail continuity remains canonical through `CanonicalNavigationContext`.
- Claim remains a TenantPilot-only assignee mutation. It leaves owner and lifecycle state unchanged, uses a lightweight preview/confirmation modal before execution, writes an audit entry, refuses silent overwrite under lock, and points the operator to the existing `My Findings` destination after success.

## Phase 1 Agent Context Update

Run:

- `.specify/scripts/bash/update-agent-context.sh copilot`

## Constitution Check — Post-Design Re-evaluation

- PASS — the design stays inside existing admin, finding, and workflow seams with no new persistence, no Graph work, no `OperationRun`, no new capability family, and no new assets.
- PASS — Livewire v4.0+ and Filament v5 constraints remain satisfied, panel provider registration stays in `apps/platform/bootstrap/providers.php`, `FindingResource` global search remains unchanged and still has a View page, and the non-destructive `Claim` action still uses an explicit lightweight preview/confirmation flow to satisfy write-governance without expanding into a broader assignment form.

## Implementation Strategy

### Phase A — Add The Canonical Shared Intake Surface

**Goal**: Create one workspace-scoped intake queue under `/admin/findings/intake`.

| Step | File | Change |
|------|------|--------|
| A.1 | `apps/platform/app/Filament/Pages/Findings/FindingsIntakeQueue.php` | Add a new Filament admin page with slug `findings/intake`, `HasTable`, workspace membership access checks, explicit `403` handling when no findings-viewable scope exists, visible-tenant resolution, active-tenant sync, and action-surface declaration for row-click inspect plus one safe `Claim` shortcut |
| A.2 | `apps/platform/resources/views/filament/pages/findings/findings-intake-queue.blade.php` | Render the page shell, page description, fixed `Unassigned` and `Needs triage` view controls, native Filament table, and calm empty-state branches with either `Clear tenant filter` or `Open my findings` |
| A.3 | `apps/platform/app/Providers/Filament/AdminPanelProvider.php` | Register the new page in the existing admin panel; do not move provider registration because it already lives in `apps/platform/bootstrap/providers.php` |

### Phase B — Derive Intake Truth From Existing Finding Semantics

**Goal**: Keep inclusion, queue reason, and ordering aligned with Specs 111, 219, and 221.

| Step | File | Change |
|------|------|--------|
| B.1 | `apps/platform/app/Filament/Pages/Findings/FindingsIntakeQueue.php` | Build the base query from `Finding`, restricted to the current workspace, visible tenant IDs, `assignee_user_id IS NULL`, and `Finding::openStatuses()` rather than `openStatusesForQuery()` |
| B.2 | `apps/platform/app/Filament/Pages/Findings/FindingsIntakeQueue.php` and `apps/platform/app/Filament/Resources/FindingResource.php` | Reuse existing severity, lifecycle, due-attention, and owner display helpers; derive queue reason as `Needs triage` for `new` and `reopened`, otherwise `Unassigned` |
| B.3 | `apps/platform/app/Filament/Pages/Findings/FindingsIntakeQueue.php` | Add visible summary counts, fixed queue-view metadata, capability-safe tenant filter options, and deterministic urgency ordering: overdue first, then reopened, then new, then remaining unassigned backlog, with due-date and finding-ID tie breaks |

### Phase C — Add The Safe Claim Shortcut Without Expanding Workflow Scope

**Goal**: Turn shared backlog into personal work in one short confirmed flow without inventing a second assignment system.

| Step | File | Change |
|------|------|--------|
| C.1 | `apps/platform/app/Filament/Pages/Findings/FindingsIntakeQueue.php` | Add one inline `Claim finding` row action using `UiEnforcement`, lightweight preview/confirmation content, preserved visibility for in-scope members, and success/failure notifications that keep the queue honest |
| C.2 | `apps/platform/app/Services/Findings/FindingWorkflowService.php` | Add a claim-specific path or guard that reuses existing assignment semantics and `AuditActionId::FindingAssigned`, but under lock refuses any record whose assignee is no longer null before mutation |
| C.3 | `apps/platform/app/Filament/Pages/Findings/FindingsIntakeQueue.php` | After confirmed claim success, refresh the queue so the row disappears immediately and provide a clear next step into `My Findings` or the tenant finding detail without changing owner or workflow state |

### Phase D — Preserve Canonical Context And Continuity

**Goal**: Make intake behave like a first-class admin-plane queue rather than a detached filter.

| Step | File | Change |
|------|------|--------|
| D.1 | `apps/platform/app/Filament/Pages/Findings/FindingsIntakeQueue.php` | Reuse `CanonicalAdminTenantFilterState` so the active tenant becomes the default prefilter and can be cleared without dropping the fixed intake scope or queue view |
| D.2 | `apps/platform/app/Filament/Pages/Findings/FindingsIntakeQueue.php` | Build row URLs to tenant finding detail with `CanonicalNavigationContext` carrying `Back to findings intake` continuity |
| D.3 | Existing tenant finding detail seam | Keep the existing tenant detail page as the deeper workflow surface and ensure it continues to consume navigation context without queue-specific detail forks |

### Phase E — Protect Visibility, Claim Safety, And Handoff Truth

**Goal**: Lock down queue inclusion, authorization, conflict handling, and continuity with focused regression coverage.

| Step | File | Change |
|------|------|--------|
| E.1 | `apps/platform/tests/Feature/Findings/FindingsIntakeQueueTest.php` | Cover visible unassigned rows only, active-tenant prefilter behavior, fixed queue views, queue reason rendering, owner-context rendering, assigned and `acknowledged` exclusion, hidden-tenant suppression, deterministic ordering, empty states, and intake-to-detail continuity |
| E.2 | `apps/platform/tests/Feature/Authorization/FindingsIntakeAuthorizationTest.php` | Cover workspace context recovery, non-member `404`, queue-access `403` when no currently viewable findings scope exists, disabled or rejected claim for members missing assign capability, and tenant-safe detail disclosure |
| E.3 | `apps/platform/tests/Feature/Findings/FindingsClaimHandoffTest.php` | Cover claim preview/confirmation rendering, successful claim, audit side effects, immediate queue removal, `My Findings` next-step alignment, and stale-row conflict refusal when another operator claims first |
| E.4 | `cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent` plus the focused Pest commands above | Run formatting and the narrowest proving suites before closing implementation |