ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
9f74f7a658
TenantAtlas/specs/214-governance-outcome-compression/plan.md
Ahmed Darrazi 9f74f7a658
Some checks failed
PR Fast Feedback / fast-feedback (pull_request) Failing after 51s
Details
feat: compress governance operator outcomes
2026-04-19 14:15:11 +02:00

339 lines
31 KiB
Markdown
Raw Blame History

# Implementation Plan: Governance Operator Outcome Compression
**Branch**: `214-governance-outcome-compression` | **Date**: 2026-04-19 | **Spec**: `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/214-governance-outcome-compression/spec.md`
**Input**: Feature specification from `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/214-governance-outcome-compression/spec.md`
**Note**: This plan keeps the work inside the existing governance truth and explanation seams. The intended implementation is a bounded compression layer for operator prominence and surface hierarchy, not a new persistence model, not a new domain-state family, and not a second explanation framework.
## Summary
Apply an operator-first compression layer to the existing governance artifact truth and explanation stack so covered baseline snapshot, evidence snapshot, tenant review, review pack, review-register, evidence-overview, and artifact-oriented operation-run surfaces answer one primary workflow question first. The implementation will reuse `ArtifactTruthPresenter`, `ArtifactTruthEnvelope`, `OperatorExplanationBuilder`, `BadgeCatalog`, existing Filament resources/pages, and current detail layouts; add a bounded `SurfaceCompressionContext` plus `CompressedGovernanceOutcome` seam at the shared UI layer; preserve current routes, actions, RBAC, and diagnostics; and expand focused Pest coverage so list, detail, register, and run-detail surfaces stay aligned.
Key approach: derive once, compress late, and keep the full truth envelope intact. The implementation will absorb into the current truth-presenter and shared-detail family rather than layering new persistence, new enums, or page-local status vocabularies.
## Technical Context
**Language/Version**: PHP 8.4.15, Laravel 12, Filament v5, Livewire v4, Blade
**Primary Dependencies**: Filament v5, Livewire v4, Pest v4, Laravel Sail, `ArtifactTruthPresenter`, `ArtifactTruthEnvelope`, `OperatorExplanationBuilder`, `BaselineSnapshotPresenter`, `BadgeCatalog`, `BadgeRenderer`, existing governance Filament resources/pages, and current Enterprise Detail builders
**Storage**: PostgreSQL via existing `baseline_snapshots`, `evidence_snapshots`, `evidence_snapshot_items`, `tenant_reviews`, `review_packs`, and `operation_runs` tables; no schema change planned
**Testing**: Pest unit and feature tests, existing Filament page/resource coverage, and shared fixture concerns under `apps/platform/tests/Feature/Concerns`
**Validation Lanes**: fast-feedback, confidence
**Target Platform**: Laravel web application in Sail locally and containerized Linux deployment in staging/production
**Project Type**: Laravel monolith web application inside the `wt-plattform` monorepo
**Performance Goals**: Preserve DB-only rendering on covered pages, avoid render-time external calls, keep per-row truth derivation lightweight enough for canonical table scans, and keep the first operator read within a 5-10 second scan window on list/register surfaces
**Constraints**: No new tables, no new domain-state families, no route changes, no new destructive actions, no new panel/provider/assets, no page-local badge taxonomy, no contradiction between list/detail/run-detail surfaces, and no drift away from existing RBAC or Action Surface rules
**Scale/Scope**: Seven operator-facing surface families, one shared governance truth seam, one shared explanation seam, one existing truth partial, and focused regression coverage across trustworthy, stale, partial, blocked, internal-only, and follow-up-needed scenarios
## UI / Surface Guardrail Plan
- **Guardrail scope**: changed surfaces
- **Native vs custom classification summary**: native Filament + shared detail primitives
- **Shared-family relevance**: governance artifact truth family, operator explanation family, shared detail family
- **State layers in scope**: page, detail, URL-query
- **Handling modes by drift class or surface**: review-mandatory on all touched surfaces; exception-required only if a surface cannot keep one dominant operator statement without breaking existing action contracts
- **Repository-signal treatment**: review-mandatory
- **Special surface test profiles**: standard-native-filament, shared-detail-family
- **Required tests or manual smoke**: functional-core, state-contract, manual-smoke
- **Exception path and spread control**: none planned; any exception must stay local to the touched surface and may not create a new shared semantics layer
- **Active feature PR close-out entry**: Guardrail
## Constitution Check
*GATE: Passed before Phase 0 research. Re-checked after Phase 1 design and still passing.*
| Principle | Pre-Research | Post-Design | Notes |
|-----------|--------------|-------------|-------|
| Inventory-first / snapshots-second | PASS | PASS | The feature changes presentation of existing governance artifacts only; snapshot and evidence ownership stay unchanged |
| Read/write separation | PASS | PASS | No new writes, preview flows, or dangerous operations are introduced |
| Graph contract path | PASS | PASS | No new Graph calls or contract-registry changes |
| Deterministic capabilities | PASS | PASS | No new capability family or resolver drift is planned |
| Workspace + tenant isolation | PASS | PASS | Canonical `/admin` pages remain tenant-safe and tenant-scoped surfaces keep current workspace + tenant entitlement behavior |
| RBAC-UX 404 vs 403 semantics | PASS | PASS | Non-members remain `404`; in-scope capability denials remain `403`; no new raw capability checks are introduced |
| Global search hard rule | PASS | PASS | No new searchable resource is added; existing resources already have detail surfaces or unchanged search posture |
| Destructive confirmation | PASS | PASS | No new destructive action is introduced; existing destructive actions keep confirmation and authorization |
| Run observability / Ops-UX | PASS | PASS | Existing `OperationRun` types and lifecycle rules stay unchanged; run-detail work is presentation-only |
| Ops-UX lifecycle ownership | PASS | PASS | No `OperationRun.status` or `outcome` transition path changes are needed |
| Ops-UX summary counts / guards | PASS | PASS | No `summary_counts` contract changes and no new operation guard exceptions |
| Data minimization | PASS | PASS | Diagnostics remain secondary and no new payload exposure is planned |
| Test governance (TEST-GOV-001) | PASS | PASS | Proof stays in targeted unit/feature coverage over existing surfaces and fixture helpers |
| Proportionality / anti-bloat | PASS | PASS | The implementation stays inside the current presenter/explanation seam and does not add persistence or a second semantic framework |
| No premature abstraction | PASS | PASS | At most one bounded compression helper/strategy is justified because the same prominence problem spans multiple real surfaces now |
| Persisted truth / behavioral state | PASS | PASS | No new table, persisted helper, or lifecycle state is required |
| UI semantics / few layers | PASS | PASS | Compression remains a thin prominence adapter over the existing envelope, not a replacement truth source |
| Badge semantics (BADGE-001) | PASS | PASS | Existing `BadgeCatalog`/`BadgeRenderer` domains remain canonical |
| Filament-native UI (UI-FIL-001) | PASS | PASS | Existing Filament tables, infolists, sections, and shared detail builders remain the primary implementation path |
| UI surface taxonomy / inspect model | PASS | PASS | Existing row-click inspect patterns, register/list/detail classifications, and action topology remain unchanged |
| Decision-first operating model (DECIDE-001) | PASS | PASS | The plan explicitly makes review/review-pack/register primary decision surfaces, baseline/evidence secondary context, and run detail tertiary evidence |
| Action-surface discipline / placeholders | PASS | PASS | No new header, row, or bulk actions are planned; redundant `View` actions remain absent |
| Operator-surface truth ordering (OPSURF-001) | PASS | PASS | Primary outcome, short reason, and next action move ahead of diagnostics across touched surfaces |
| Filament UX-001 | PASS | PASS | Existing tables and infolists remain; detail-page hierarchy is tightened without layout drift |
| Filament v5 / Livewire v4 compliance | PASS | PASS | The work remains entirely within the current Filament v5 + Livewire v4 stack |
| Provider registration location | PASS | PASS | No panel/provider work; Laravel 11+ provider registration remains in `bootstrap/providers.php` |
| Asset strategy | PASS | PASS | No new global or on-demand assets are required; existing `filament:assets` deployment step remains unchanged |
## Test Governance Check
- **Test purpose / classification by changed surface**: `Feature` for list/detail/register/run-detail surfaces plus narrow `Unit` coverage for the shared compression value object and surface-context mapping
- **Affected validation lanes**: `fast-feedback`, `confidence`
- **Why this lane mix is the narrowest sufficient proof**: The feature is proven by operator-visible hierarchy and cross-surface agreement on existing pages. That requires focused surface and presenter tests, not browser or heavy-governance breadth.
- **Narrowest proving command(s)**: `cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Evidence/EvidenceSnapshotResourceTest.php tests/Feature/TenantReview/TenantReviewRegisterTest.php tests/Feature/ReviewPack/ReviewPackResourceTest.php tests/Feature/Evidence/EvidenceOverviewPageTest.php tests/Feature/Filament/OperationRunBaselineTruthSurfaceTest.php`; `cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan test --compact --filter=GovernanceOutcomeCompression`
- **Fixture / helper / factory / seed / context cost risks**: Moderate reuse of `BuildsGovernanceArtifactTruthFixtures` and existing seeded truth states; risk is overloading shared helpers with too many surface-specific defaults
- **Expensive defaults or shared helper growth introduced?**: no; any new fixture helper must stay opt-in by artifact state and surface family
- **Heavy-family additions, promotions, or visibility changes**: none
- **Surface-class relief / special coverage rule**: `shared-detail-family` coverage is required for detail pages and run detail; list/register surfaces keep ordinary native Filament coverage
- **Closing validation and reviewer handoff**: Reviewers must confirm one dominant operator statement per artifact, secondary diagnostics only, and no new page-local badge language. Re-run the focused command above plus the new/updated compression-focused suite.
- **Budget / baseline / trend follow-up**: Low-to-moderate assertion growth inside existing suites; no separate follow-up spec needed unless shared fixture cost starts to spread beyond governance artifact tests
- **Review-stop questions**: Does the change stay in the presenter/shared-detail seam? Did helper growth stay opt-in? Did any touched surface add a second primary outcome or new action furniture? Did any new abstraction become broader than current-release need?
- **Escalation path**: document-in-feature unless a second shared semantic layer or new persistent helper is proposed, in which case reject-or-split
- **Active feature PR close-out entry**: Guardrail
- **Why no dedicated follow-up spec is needed**: The suite cost and architectural surface remain bounded to the already-covered governance artifact family and do not create a new recurring test family or platform framework
## Phase 0 Research
Research outcomes are captured in `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/214-governance-outcome-compression/research.md`.
Key decisions:
- Keep `ArtifactTruthPresenter` and `ArtifactTruthEnvelope` as the single canonical truth seam and add compression only as a derived prominence layer.
- Make surface-family context explicit so baseline/evidence surfaces prioritize usability while review/review-pack surfaces prioritize publication/shareability.
- Reuse `OperatorExplanationBuilder`, `BadgeCatalog`, and the existing governance truth partial instead of inventing page-local summary systems.
- Preserve diagnostics, raw reason structures, and audit-visible truth by moving them into secondary or diagnostics tiers instead of deleting them.
- Align artifact-oriented run detail with the same compressed decision direction used on the linked artifact surfaces.
- Reuse current fixture concerns and surface suites rather than creating a new UI harness.
## Phase 1 Design
Design artifacts are created under `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/214-governance-outcome-compression/`:
- `research.md`: implementation-seam decisions and rejected alternatives for bounded outcome compression
- `data-model.md`: logical model for derived compression context, compressed outcomes, secondary facts, and diagnostics tiering
- `contracts/governance-outcome-compression.logical.openapi.yaml`: internal logical contract for rendered HTML surfaces and their structured compressed-outcome payloads
- `quickstart.md`: focused verification workflow for manual and automated validation
Design decisions:
- No schema migration is required; all compressed operator outcomes remain derived from existing persisted artifact truth and existing relationships.
- The primary implementation seam is the current governance truth presenter and shared detail/rendering layer, optionally with one bounded compression strategy/value object keyed by surface family.
- Existing Filament action topology, route shape, authorization behavior, and destructive-action semantics remain unchanged.
- The existing `resources/views/filament/infolists/entries/governance-artifact-truth.blade.php` partial and current detail builders remain the rendering family to extend instead of introducing a second surface family.
- Canonical summary pages and run detail must reuse the same decision direction as tenant detail pages rather than inventing row-local or run-local status dialects.
## Project Structure
### Documentation (this feature)
```text
specs/214-governance-outcome-compression/
├── spec.md
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── contracts/
│ └── governance-outcome-compression.logical.openapi.yaml
├── checklists/
│ └── requirements.md
└── tasks.md
```
### Source Code (repository root)
```text
apps/platform/
├── app/
│ ├── Filament/
│ │ ├── Pages/
│ │ │ ├── Monitoring/
│ │ │ │ └── EvidenceOverview.php
│ │ │ ├── Operations/
│ │ │ │ └── TenantlessOperationRunViewer.php
│ │ │ └── Reviews/
│ │ │ └── ReviewRegister.php
│ │ └── Resources/
│ │ ├── BaselineSnapshotResource.php
│ │ ├── EvidenceSnapshotResource.php
│ │ ├── OperationRunResource.php
│ │ ├── ReviewPackResource.php
│ │ └── TenantReviewResource.php
│ ├── Services/
│ │ └── Baselines/
│ │ └── SnapshotRendering/
│ │ └── BaselineSnapshotPresenter.php
│ └── Support/
│ ├── Badges/
│ │ ├── BadgeCatalog.php
│ │ └── BadgeRenderer.php
│ └── Ui/
│ ├── GovernanceArtifactTruth/
│ │ ├── CompressedGovernanceOutcome.php
│ │ ├── ArtifactTruthEnvelope.php
│ │ ├── ArtifactTruthPresenter.php
│ │ ├── ArtifactTruthDimension.php
│ │ └── SurfaceCompressionContext.php
│ └── OperatorExplanation/
│ └── OperatorExplanationBuilder.php
├── resources/
│ └── views/
│ └── filament/
│ └── infolists/
│ └── entries/
│ └── governance-artifact-truth.blade.php
└── tests/
├── Unit/
│ └── Support/
│ └── Ui/
│ └── GovernanceArtifactTruth/
│ └── CompressedGovernanceOutcomeTest.php
└── Feature/
├── Concerns/
│ └── BuildsGovernanceArtifactTruthFixtures.php
├── Evidence/
│ ├── EvidenceOverviewPageTest.php
│ └── EvidenceSnapshotResourceTest.php
├── Filament/
│ ├── EvidenceOverviewDerivedStateMemoizationTest.php
│ ├── OperationRunBaselineTruthSurfaceTest.php
│ └── ReviewRegisterDerivedStateMemoizationTest.php
├── ReviewPack/
│ ├── ReviewPackResourceTest.php
│ └── TenantReviewDerivedReviewPackTest.php
└── TenantReview/
├── TenantReviewExplanationSurfaceTest.php
├── TenantReviewLifecycleTest.php
├── TenantReviewRegisterTest.php
└── TenantReviewUiContractTest.php
```
**Structure Decision**: Standard Laravel monolith. The work stays concentrated in the current governance truth presenter, explanation builder, touched Filament resources/pages, one shared truth partial, and focused Pest suites. No new base directory, no new domain package, and no new panel surface are required.
## Implementation Strategy
### Phase A — Introduce One Bounded Compression Seam
**Goal**: Add a thin derived seam that classifies existing artifact truth into primary, secondary, and diagnostics tiers by surface family.
| Step | File | Change |
|------|------|--------|
| A.1 | `apps/platform/app/Support/Ui/GovernanceArtifactTruth/SurfaceCompressionContext.php` and `apps/platform/app/Support/Ui/GovernanceArtifactTruth/CompressedGovernanceOutcome.php` | Introduce the bounded surface-aware types that choose a dominant operator outcome, centralized badge, short reason, and next step without persisting new truth |
| A.2 | `apps/platform/app/Support/Ui/GovernanceArtifactTruth/ArtifactTruthPresenter.php` | Keep the full envelope intact while deriving one dominant compressed outcome and `BadgeCatalog`-backed primary badge from existing truth dimensions |
| A.3 | `apps/platform/app/Support/Ui/OperatorExplanation/OperatorExplanationBuilder.php` and `apps/platform/app/Support/Ui/GovernanceArtifactTruth/ArtifactTruthEnvelope.php` | Expose translated operator-first summary inputs and serialize them without leaking architecture-first wording |
### Phase B — Simplify List and Register Surfaces
**Goal**: Make covered list and register rows answer the primary workflow question first without expanding action furniture or route structure.
| Step | File | Change |
|------|------|--------|
| B.1 | `apps/platform/app/Filament/Resources/BaselineSnapshotResource.php` | Reduce equal-weight scan noise so snapshot lists foreground one usability outcome, one short reason, and one next step |
| B.2 | `apps/platform/app/Filament/Resources/EvidenceSnapshotResource.php` | Foreground evidence usability rather than parallel semantic columns |
| B.3 | `apps/platform/app/Filament/Resources/TenantReviewResource.php` and `apps/platform/app/Filament/Resources/ReviewPackResource.php` | Make publication/shareability the primary row-level decision while keeping secondary facts available |
| B.4 | `apps/platform/app/Filament/Pages/Reviews/ReviewRegister.php` and `apps/platform/app/Filament/Pages/Monitoring/EvidenceOverview.php` | Align canonical rows with the same compressed decision direction used by tenant detail surfaces while preserving tenant-prefilter continuity and entitlement-safe rendering |
### Phase C — Reorder Detail Surfaces Around The First Decision
**Goal**: Ensure detail screens lead with outcome, short explanation, and next step before diagnostics.
| Step | File | Change |
|------|------|--------|
| C.1 | `apps/platform/app/Services/Baselines/SnapshotRendering/BaselineSnapshotPresenter.php` | Move baseline snapshot detail emphasis toward compressed usability summary while preserving technical sections |
| C.2 | `apps/platform/resources/views/filament/infolists/entries/governance-artifact-truth.blade.php` | Render primary/secondary/diagnostics tiers instead of treating every semantic axis as equal default-visible content |
| C.3 | `apps/platform/app/Filament/Resources/TenantReviewResource.php` and `apps/platform/app/Filament/Resources/ReviewPackResource.php` | Keep existing detail actions and route behavior but strengthen summary-first hierarchy for review and pack detail |
### Phase D — Keep Run Detail Directionally Consistent
**Goal**: Make artifact-oriented Monitoring run detail explain the dominant artifact impact without contradicting the linked artifact surfaces.
| Step | File | Change |
|------|------|--------|
| D.1 | `apps/platform/app/Support/Ui/GovernanceArtifactTruth/ArtifactTruthPresenter.php` | Reuse the same compressed decision direction for `OperationRun` envelopes that explain artifact outcomes |
| D.2 | `apps/platform/app/Filament/Resources/OperationRunResource.php` and `apps/platform/app/Filament/Pages/Operations/TenantlessOperationRunViewer.php` | Lead with dominant artifact impact and next step while keeping raw diagnostics secondary |
| D.3 | Related navigation helpers in the current run-detail family | Preserve existing routes and action hierarchy; no new run action is introduced |
### Phase E — Regression Protection And Verification
**Goal**: Add the smallest valuable test set that protects cross-surface agreement, prominence rules, and diagnostics demotion.
| Step | File | Change |
|------|------|--------|
| E.1 | `apps/platform/tests/Feature/Concerns/BuildsGovernanceArtifactTruthFixtures.php` | Add or extend opt-in helpers for trustworthy, stale, partial, blocked, internal-only, and follow-up-needed artifact states |
| E.2 | `apps/platform/tests/Unit/Support/Ui/GovernanceArtifactTruth/CompressedGovernanceOutcomeTest.php` | Assert surface-context mapping, centralized badge reuse, and operator-facing summary vocabulary |
| E.3 | `apps/platform/tests/Feature/Evidence/EvidenceSnapshotResourceTest.php` and `apps/platform/tests/Feature/Evidence/EvidenceOverviewPageTest.php` | Assert one dominant operator outcome on snapshot and overview surfaces, plus canonical-view prefilter continuity and deny-as-not-found behavior |
## Close-out Proof
- **Implementation status**: shared compression seam, summary-tier rendering, list/detail/register/run-detail wiring, fixture support, and derived-state memoization coverage completed
- **Guardrail status**: PASS
The touched list and registry surfaces preserve one inspect model, bounded row actions, session-persisted table state where required, badge-backed status columns, and deny-as-not-found semantics for non-members
- **Focused automated verification**: PASS on 2026-04-19
`cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/Ui/GovernanceArtifactTruth/CompressedGovernanceOutcomeTest.php tests/Feature/Filament/ReviewRegisterDerivedStateMemoizationTest.php tests/Feature/Filament/EvidenceOverviewDerivedStateMemoizationTest.php tests/Feature/Filament/BaselineSnapshotListFiltersTest.php tests/Feature/Filament/BaselineSnapshotTruthSurfaceTest.php tests/Feature/Filament/BaselineSnapshotDegradedStateTest.php tests/Feature/Evidence/EvidenceSnapshotResourceTest.php tests/Feature/Evidence/EvidenceOverviewPageTest.php tests/Feature/TenantReview/TenantReviewRegisterTest.php tests/Feature/TenantReview/TenantReviewExplanationSurfaceTest.php tests/Feature/TenantReview/TenantReviewUiContractTest.php tests/Feature/ReviewPack/ReviewPackResourceTest.php tests/Feature/ReviewPack/TenantReviewDerivedReviewPackTest.php tests/Feature/Filament/OperationRunBaselineTruthSurfaceTest.php tests/Unit/Baselines/SnapshotRendering/BaselineSnapshotPresenterTest.php`
- **Focused suite result**: `68` tests passed, `445` assertions
- **Formatting**: PASS
`cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail bin pint --dirty --format agent`
- **Validation lanes**: `fast-feedback` PASS, `confidence` PASS
- **Filament / platform checks**:
Livewire v4.0+ compliant, no provider registration changes were required, no global-search posture changed beyond existing disabled resources with retained view pages, destructive actions kept `->action(...)` plus `->requiresConfirmation()`, and no new asset registration or deployment asset step was introduced
- **Test-governance disposition**: `document-in-feature`
- **Manual smoke note**: browser-based ten-second scan signoff is still recommended for a human reviewer, but architecture-first label leakage and summary-order regressions are covered by the focused suite above
| E.4 | `apps/platform/tests/Feature/TenantReview/TenantReviewRegisterTest.php`, `TenantReviewExplanationSurfaceTest.php`, and `TenantReviewUiContractTest.php` | Assert compressed review/register hierarchy, combined-limiters, and agreement between list and detail |
| E.5 | `apps/platform/tests/Feature/ReviewPack/ReviewPackResourceTest.php` and `TenantReviewDerivedReviewPackTest.php` | Assert pack shareability compression, combined-limiters, and no architecture-first primary labels |
| E.6 | `apps/platform/tests/Feature/Filament/OperationRunBaselineTruthSurfaceTest.php` | Assert run-detail outcome direction stays consistent with linked artifact truth |
| E.7 | `cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent` plus focused Pest runs and the quickstart smoke pass | Required formatting, targeted validation, and manual 10-second scan verification before task completion |
## Key Design Decisions
### D-001 — The full truth envelope remains canonical
`ArtifactTruthEnvelope` stays the full semantic source for existence, content, freshness, publication readiness, support, actionability, reason, and diagnostics. Compression decides prominence, not truth.
### D-002 — Surface-family context decides primacy
Baseline and evidence surfaces primarily answer usability and trustworthiness. Review and review-pack surfaces primarily answer publishability or shareability. Canonical registers and run detail must reflect the same decision direction rather than inventing independent local priorities.
### D-003 — Diagnostics are demoted, not deleted
Raw reason structures, fidelity sub-axes, JSON context, and supporting badge families remain available in secondary or technical sections. The feature reduces default-visible noise without throwing away operator-grade proof.
### D-004 — Existing Filament actions and routes are part of the guardrail
This slice is intentionally not an action-topology change. It keeps row-click inspect, current resource/page routes, current dangerous-action placement, and current capability gating while making the visible explanation calmer.
### D-005 — Shared caching must stay context-safe
The current request-scoped derived-state path already caches truth envelopes. If a new compression helper is memoized, its cache key must include the surface-family context so review-pack or register views do not accidentally reuse baseline-specific prominence rules.
## Risk Assessment
| Risk | Impact | Likelihood | Mitigation |
|------|--------|------------|------------|
| Compression becomes a second truth layer instead of a thin prominence adapter | High | Medium | Keep the implementation downstream of `ArtifactTruthEnvelope` and prohibit new persisted or page-local semantic helpers |
| Review and pack surfaces choose different dominant outcomes for the same artifact burden | High | Medium | Centralize context rules and add explicit review-vs-pack alignment tests |
| List simplification hides information operators still need for decisions | Medium | Medium | Keep secondary facts visible in bounded slots and validate with list-surface review checklist plus manual smoke |
| Run detail diverges from artifact detail after drill-through | Medium | Medium | Reuse the same compressed direction on `OperationRun` truth and add parity assertions in `OperationRunBaselineTruthSurfaceTest` |
| Shared fixture helpers become too broad and expensive | Medium | Low | Keep new state builders opt-in and scope them to governance artifact tests only |
## Test Strategy
- Extend existing governance artifact truth fixtures instead of creating a new harness.
- Add explicit canonical-view authorization and tenant-prefilter regressions for `/admin/reviews` and `/admin/evidence/overview` instead of relying on implicit coverage.
- Add compression-focused assertions to current evidence, review, review-pack, review-register, evidence-overview, and run-detail suites.
- Add explicit combined-limiter and operator-vocabulary assertions so dominant-outcome ranking and architecture-first label suppression are protected.
- Add narrow unit coverage for the shared compression value object and surface-context mapping while keeping the primary proof in feature-level surface tests.
- Preserve current authorization semantics: non-entitled users remain `404`, in-scope capability denials remain `403`, and view-only users can still inspect truth without gaining new actions.
- Keep existing Action Surface and badge guards green so the feature cannot regress into ad-hoc status language or redundant inspect actions.
- Manual validation must confirm the 10-second scan goal, operator-first wording, and no architecture-first label leakage on one list/register surface, one detail surface, and one artifact-oriented run detail page per artifact family.
## Complexity Tracking
| Violation | Why Needed | Simpler Alternative Rejected Because |
|-----------|------------|-------------------------------------|
| One bounded compression strategy or value object over the existing truth envelope | The same prominence problem now spans multiple real surfaces with different operator questions, so one shared derived rule is cheaper and safer than copy-paste prominence logic in each page/resource | Pure page-local copy cleanup would drift into inconsistent decision language and duplicate cross-surface mapping logic |
## Proportionality Review
- **Current operator problem**: Governance artifact truth is correct but too decomposed on first read, forcing operators to synthesize basic decisions across several equal-weight semantic cues.
- **Existing structure is insufficient because**: The current presenter and explanation stack expose the right truth but do not yet decide which message is primary for each surface family, so list/detail/run surfaces can still over-explain or emphasize the wrong dimension first.
- **Narrowest correct implementation**: Add one thin derived compression seam downstream of the existing truth envelope and use it across the already-covered artifact surfaces.
- **Ownership cost created**: A small amount of new mapping logic, cache-context care, and regression coverage to keep list/detail/register/run-detail alignment stable.
- **Alternative intentionally rejected**: Page-local column or copy cleanup on each touched surface. That is cheaper initially but reintroduces dialect drift and makes cross-surface parity harder to maintain.
- **Release truth**: Current-release truth. This is the adoption layer that makes already-shipped governance truth operable now, not speculative future infrastructure.
Reference in New Issue View Git Blame Copy Permalink