ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
bf8d59e034
TenantAtlas/specs/284-provider-neutral-artifact-source-taxonomy/tasks.md
Ahmed Darrazi bf8d59e034
Some checks failed
PR Fast Feedback / fast-feedback (pull_request) Failing after 1m36s
Details
feat: implement provider-neutral artifact source taxonomy
2026-05-09 01:45:12 +02:00

24 KiB
Raw Blame History

description
Task list for Provider-neutral Artifact Source Taxonomy

Tasks: Provider-neutral Artifact Source Taxonomy

Input: Design documents from specs/284-provider-neutral-artifact-source-taxonomy/
Prerequisites: specs/284-provider-neutral-artifact-source-taxonomy/spec.md, specs/284-provider-neutral-artifact-source-taxonomy/plan.md, specs/284-provider-neutral-artifact-source-taxonomy/checklists/requirements.md, specs/284-provider-neutral-artifact-source-taxonomy/research.md, specs/284-provider-neutral-artifact-source-taxonomy/data-model.md, specs/284-provider-neutral-artifact-source-taxonomy/quickstart.md, and specs/284-provider-neutral-artifact-source-taxonomy/contracts/provider-neutral-artifact-source-taxonomy.logical.openapi.yaml
Implementation Posture: Runtime implementation explicitly accepted on 2026-05-09. Targeted test execution, browser smoke, and dirty-file formatting validation remain required before merge readiness.
Tests: REQUIRED (Pest). Keep proof bounded to apps/platform/tests/Unit/Artifacts/ArtifactSourceTaxonomyCatalogTest.php, apps/platform/tests/Unit/Inventory/InventoryCanonicalTypeDescriptorTest.php, apps/platform/tests/Feature/Artifacts/FindingArtifactSourceTaxonomyTest.php, apps/platform/tests/Feature/Artifacts/EvidenceSnapshotSourceTaxonomyTest.php, apps/platform/tests/Feature/Artifacts/StoredReportSourceTaxonomyTest.php, apps/platform/tests/Feature/Artifacts/InventoryArtifactTypeTaxonomyTest.php, apps/platform/tests/Feature/Filament/Artifacts/ArtifactSourceTaxonomySurfaceTest.php, apps/platform/tests/Feature/Guards/ArtifactSourceProviderTruthGuardTest.php, and apps/platform/tests/Browser/Spec284ArtifactSourceTaxonomySmokeTest.php.
Operations: No new OperationRun family. Reuse existing read-only operation lineage where OperationsSummarySource, OperationRunLinks, or adjacent presenters already surface operation context. 284 does not change start, completion, or link UX for operation execution.
RBAC: Workspace membership remains the first 404 boundary, managed-environment entitlement remains the second 404 boundary, and current findings, evidence, reports, inventory, and review capability denials remain 403. Provider-neutral artifact typing must not bypass existing policies or capabilities.
Shared Pattern Reuse: Reuse PlatformVocabularyGlossary, GovernanceSubjectTaxonomyRegistry, CanonicalControlResolutionRequest, CanonicalControlResolver, EvidenceSnapshotService, InventoryPolicyTypeMeta, ArtifactTruthPresenter, TenantReviewSectionFactory, and touched support or AI source_family consumers. Do not introduce a provider framework, a detector catalog, a full control-catalog expansion, a package runtime, a new artifact table, historical backfill, or adjacent Spec 285 through 287 scope.
Filament / Panel Guardrails: Filament remains v5 on Livewire v4. Provider registration remains in apps/platform/bootstrap/providers.php. FindingResource and InventoryItemResource keep valid View pages for any current or future search posture. EvidenceSnapshotResource, StoredReportResource, and TenantReviewResource remain non-globally-searchable while keeping View pages. Any touched destructive action must continue to use ->action(...), ->requiresConfirmation(), and current server authorization. Asset strategy stays unchanged.
Compatibility Posture: Reject historical backfill, dual-write compatibility paths, a new artifact table, a detector catalog, package runtime, a provider framework, RBAC redesign, route-shell work, copy neutralization, and no-legacy enforcement work.
External Prerequisite: Specs 281, 282, and 283 must already be merged or otherwise present on the implementation branch before any runtime or test task starts, and SCOPE-001 ownership compliance for touched tenant-owned artifact tables must be satisfied or explicitly excepted before runtime implementation begins.
Organization: Tasks are grouped by user story so descriptor derivation, inventory type splitting, operator-surface disclosure, and downstream source-family alignment remain independently testable.
Review Outcome: implementation-ready
Workflow Outcome: keep
Test-governance Outcome: keep

Prerequisite Resolution: SCOPE-001 is no longer a blocking prerequisite for this implementation loop. Specs 281, 282, and 283 are present on the branch, Spec 279 records the approved managed-environment core exception, and current touched artifact tables carry the established workspace plus managed-environment ownership boundary. 284 still must not add a new table, descriptor columns, historical backfill, detector catalog, package runtime, provider framework, or adjacent Specs 285 through 287 scope.

Test Governance Checklist

  • Lane assignment stays fast-feedback, confidence, and one narrow browser lane.
  • New or changed tests stay in the named unit, feature, guard, and browser files only.
  • Workspace, managed-environment, finding, evidence, stored-report, review, and inventory fixtures remain explicit and opt-in; no hidden shared defaults or backfill helpers are planned.
  • Planned validation commands match spec.md, plan.md, and quickstart.md exactly.
  • standard-native-filament and shared-detail-family expectations stay explicit for touched surfaces.
  • Any attempt to absorb Specs 285 through 287 resolves as split or reject-or-split, not hidden follow-up inside 284.

Pinned Initial Descriptor Inventories

  • source_family:
    • finding
    • stored_report
    • evidence_snapshot
    • inventory
    • operation_run
  • source_kind:
    • model_summary
    • stored_report
    • operation_rollup
    • inventory_projection
  • source_target_kind:
    • managed_environment
    • governed_subject
    • provider_connection
    • operation_run

This pinned inventory is authoritative for Spec 284 tasks and must remain identical across the package.

Phase 0: External Gate

Purpose: Confirm the inherited provider-boundary and artifact-surface prerequisites are available before implementation begins.

  • T000 Confirm Specs 281, 282, and 283 are already merged or otherwise present on the implementation branch before any runtime or test task begins.

Phase 1: Setup (Shared Context)

Purpose: Confirm the bounded artifact-source inventory, proof files, and deferred-scope posture before runtime edits begin.

  • T001 Review specs/284-provider-neutral-artifact-source-taxonomy/spec.md, plan.md, checklists/requirements.md, research.md, data-model.md, quickstart.md, and contracts/provider-neutral-artifact-source-taxonomy.logical.openapi.yaml together so implementation stays on Spec 284 only, and stop for a prerequisite decision if SCOPE-001 ownership compliance is still unresolved for touched tenant-owned artifact tables.
  • T002 [P] Confirm the current persisted-truth seams in apps/platform/app/Models/Finding.php, apps/platform/app/Models/EvidenceSnapshotItem.php, apps/platform/app/Models/StoredReport.php, apps/platform/app/Models/InventoryItem.php, and the related migrations before changing descriptor fields.
  • T003 [P] Confirm the current evidence-source and control-resolution seams in apps/platform/app/Services/Evidence/Contracts/EvidenceSourceProvider.php, apps/platform/app/Services/Evidence/EvidenceSnapshotService.php, apps/platform/app/Services/Evidence/Sources/FindingsSummarySource.php, apps/platform/app/Services/Evidence/Sources/PermissionPostureSource.php, apps/platform/app/Services/Evidence/Sources/EntraAdminRolesSource.php, apps/platform/app/Services/Evidence/Sources/BaselineDriftPostureSource.php, apps/platform/app/Services/Evidence/Sources/OperationsSummarySource.php, apps/platform/app/Support/Governance/Controls/CanonicalControlResolutionRequest.php, and apps/platform/app/Support/Governance/Controls/CanonicalControlResolver.php.
  • T004 [P] Confirm the current inventory type and metadata seams in apps/platform/app/Support/Inventory/InventoryPolicyTypeMeta.php, apps/platform/app/Models/InventoryItem.php, and apps/platform/app/Filament/Resources/InventoryItemResource.php before changing policy_type semantics.
  • T005 [P] Confirm the current operator-surface and review-summary seams in apps/platform/app/Filament/Resources/FindingResource.php, EvidenceSnapshotResource.php, StoredReportResource.php, TenantReviewResource.php, apps/platform/app/Services/TenantReviews/TenantReviewSectionFactory.php, and apps/platform/app/Support/Ui/GovernanceArtifactTruth/ArtifactTruthPresenter.php.
  • T006 [P] Confirm current source_family naming precedent and deferred boundaries in apps/platform/app/Support/SupportDiagnostics/SupportDiagnosticBundleBuilder.php, apps/platform/app/Support/Ai/AiUseCaseCatalog.php, and specs/284-provider-neutral-artifact-source-taxonomy/checklists/requirements.md so Specs 285 through 287 remain explicitly out of scope.

Phase 2: Foundational (Blocking Prerequisites)

Purpose: Establish the proving suite and the canonical descriptor inventory that every story depends on.

Critical: No user-story work should begin until this phase is complete.

  • T007 [P] Add failing coverage in apps/platform/tests/Unit/Artifacts/ArtifactSourceTaxonomyCatalogTest.php for the exact source_family, source_kind, and source_target_kind inventories plus the no-detector-catalog rule.
  • T008 [P] Add failing coverage in apps/platform/tests/Unit/Inventory/InventoryCanonicalTypeDescriptorTest.php for the canonical_type, provider_object_type, provider_display_type, and legacy_policy_type split.
  • T009 [P] Add failing coverage in apps/platform/tests/Feature/Artifacts/FindingArtifactSourceTaxonomyTest.php, apps/platform/tests/Feature/Artifacts/EvidenceSnapshotSourceTaxonomyTest.php, and apps/platform/tests/Feature/Artifacts/StoredReportSourceTaxonomyTest.php for shared descriptor derivation over findings, evidence, and stored reports, including workspace_id, tenant_id, provider_connection_id, and source_target_identifier semantics when present.
  • T010 [P] Add failing guard coverage in apps/platform/tests/Feature/Guards/ArtifactSourceProviderTruthGuardTest.php for finding_type, report_type, or policy_type reappearing as top-level summary truth and for package_run_id being treated as active runtime truth.
  • T011 [P] Add the narrow browser smoke in apps/platform/tests/Browser/Spec284ArtifactSourceTaxonomySmokeTest.php for one finding, one evidence snapshot, one stored report, one inventory item, and one tenant-review section under the live Filament shell.
  • T012 Introduce the bounded shared descriptor support seam in the smallest viable namespace under apps/platform/app/Support/Artifacts/ or existing helpers, derive the descriptor from existing persisted truth plus the established workspace and tenant scope, carry provider_connection_id and source_target_identifier when current truth exposes them, and pin the exact inventories across consumers without adding a new table, detector catalog, descriptor columns, or backfill flow.

Checkpoint: The proving files exist, the descriptor inventory is explicit, and later stories can consume one canonical artifact-source contract.

Phase 3: User Story 1 - Interpret findings, evidence, and stored reports with one descriptor (Priority: P1)

Goal: Findings, evidence summaries, and stored reports expose the same canonical artifact-source descriptor and control summary before provider-native detail.

Independent Test: Load one finding, one evidence snapshot item, and one stored report for the same managed environment and confirm each surface or reader exposes the same descriptor-first summary contract.

Tests for User Story 1

  • T013 [P] [US1] Extend apps/platform/tests/Feature/Artifacts/FindingArtifactSourceTaxonomyTest.php, apps/platform/tests/Feature/Artifacts/EvidenceSnapshotSourceTaxonomyTest.php, and apps/platform/tests/Feature/Artifacts/StoredReportSourceTaxonomyTest.php after T012 to prove the same descriptor and control_key semantics survive across finding, evidence, and stored-report readers.

Implementation for User Story 1

  • T014 [US1] Update apps/platform/app/Models/Finding.php, apps/platform/app/Services/Evidence/Sources/FindingsSummarySource.php, and the smallest related control-binding seam so finding summaries derive the canonical descriptor without page-local Microsoft-only checks.
  • T015 [US1] Update apps/platform/app/Services/Evidence/Contracts/EvidenceSourceProvider.php, apps/platform/app/Services/Evidence/EvidenceSnapshotService.php, apps/platform/app/Services/Evidence/Sources/PermissionPostureSource.php, apps/platform/app/Services/Evidence/Sources/EntraAdminRolesSource.php, apps/platform/app/Services/Evidence/Sources/BaselineDriftPostureSource.php, apps/platform/app/Services/Evidence/Sources/OperationsSummarySource.php, and apps/platform/app/Models/EvidenceSnapshotItem.php so evidence summaries derive the descriptor consistently from existing persisted truth.
  • T016 [US1] Update apps/platform/app/Models/StoredReport.php, apps/platform/app/Services/EntraAdminRoles/EntraAdminRolesReportService.php, and any directly touched stored-report readers so report summaries align to source-family semantics while keeping raw report_type nested. Note: no EntraAdminRolesReportService edit was required because the shared StoredReport resolver derives descriptor and provider detail from existing report payloads without producer changes.

Checkpoint: Findings, evidence summaries, and stored reports now expose one shared descriptor-first lineage contract.

Phase 4: User Story 2 - Read inventory items with canonical and provider type separation (Priority: P1)

Goal: Inventory items distinguish platform-owned canonical type from provider-owned object type and display type while still participating in the shared artifact-source descriptor contract.

Independent Test: Open one inventory item and confirm the page shows canonical_type, provider_object_type, and provider_display_type as separate concepts and still exposes the shared source descriptor.

Tests for User Story 2

  • T017 [P] [US2] Extend apps/platform/tests/Unit/Inventory/InventoryCanonicalTypeDescriptorTest.php and apps/platform/tests/Feature/Artifacts/InventoryArtifactTypeTaxonomyTest.php after T012 to prove the inventory type split, legacy policy_type nesting, and shared source descriptor on inventory read models.

Implementation for User Story 2

  • T018 [US2] Update apps/platform/app/Support/Inventory/InventoryPolicyTypeMeta.php and the smallest adjacent inventory read-model seam so inventory emits canonical_type, provider_object_type, provider_display_type, and optional legacy_policy_type without promoting raw policy_type back to top-level truth.
  • T019 [US2] Update apps/platform/app/Models/InventoryItem.php and apps/platform/app/Filament/Resources/InventoryItemResource.php so list and detail surfaces disclose the type split, carry the shared source descriptor, and keep raw metadata secondary.

Checkpoint: Inventory surfaces now separate platform type from provider object type cleanly.

Phase 5: User Story 3 - Keep operator-facing artifact surfaces descriptor-first (Priority: P2)

Goal: Findings, evidence, stored reports, and tenant-review sections show the canonical descriptor and control summary before provider-native detail.

Independent Test: Open one finding, one evidence snapshot, one stored report, and one tenant review with supporting sections and confirm each touched summary is descriptor-first.

Tests for User Story 3

  • T020 [P] [US3] Extend apps/platform/tests/Feature/Filament/Artifacts/ArtifactSourceTaxonomySurfaceTest.php after T012 to prove FindingResource, EvidenceSnapshotResource, InventoryItemResource, StoredReportResource, and TenantReviewResource surface the descriptor first, provider detail second, and preserve inherited 404 versus 403 behavior.

Implementation for User Story 3

  • T021 [US3] Update apps/platform/app/Filament/Resources/FindingResource.php, apps/platform/app/Filament/Resources/EvidenceSnapshotResource.php, apps/platform/app/Filament/Resources/StoredReportResource.php, apps/platform/app/Filament/Resources/TenantReviewResource.php, apps/platform/app/Services/TenantReviews/TenantReviewSectionFactory.php, and apps/platform/app/Support/Ui/GovernanceArtifactTruth/ArtifactTruthPresenter.php so summary ordering converges on the shared descriptor and control summary. Note: no ArtifactTruthPresenter edit was required because descriptor-first disclosure lives in the resource and review-section summary layers while existing truth envelopes remain unchanged.
  • T022 [US3] Update touched review or evidence related-context seams only where required so navigation stays unchanged while summary ordering converges. Note: no related-context changes were required; existing links stayed unchanged.

Checkpoint: Operator-facing read paths now teach one artifact-source vocabulary and keep provider detail secondary.

Phase 6: User Story 4 - Align downstream shared consumers without adding package runtime (Priority: P3)

Goal: Touched support or AI source_family consumers reuse the same pinned family names and keep package_run_id optional only.

Independent Test: Inspect touched support or AI source-family bundles and confirm they use the same source-family vocabulary as the artifact descriptor while leaving package_run_id null or absent.

Tests for User Story 4

  • T023 [P] [US4] Extend apps/platform/tests/Feature/Guards/ArtifactSourceProviderTruthGuardTest.php after T012 to prove touched support or AI source_family consumers use the pinned family names and that package_run_id remains optional-only in current runtime.

Implementation for User Story 4

  • T024 [US4] Update apps/platform/app/Support/SupportDiagnostics/SupportDiagnosticBundleBuilder.php, apps/platform/app/Support/Ai/AiUseCaseCatalog.php, and any directly touched shared descriptor helpers only where required so source-family semantics align without implying package runtime. Note: no runtime edit was required because existing support and AI families remain non-artifact source families and the guard test proves they do not collide with the pinned artifact inventory.

Checkpoint: Downstream shared consumers no longer risk inventing a second artifact-source vocabulary.

Phase 7: Polish & Cross-Cutting Validation

Purpose: Run the exact bounded proof set, perform the final Filament and taxonomy review, and confirm the slice stayed inside Spec 284.

  • T025 [P] Run export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && REPO_ROOT="$(git rev-parse --show-toplevel)" && (cd "$REPO_ROOT/apps/platform" && ./vendor/bin/sail artisan test --compact tests/Unit/Artifacts/ArtifactSourceTaxonomyCatalogTest.php tests/Unit/Inventory/InventoryCanonicalTypeDescriptorTest.php).
  • T026 [P] Run export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && REPO_ROOT="$(git rev-parse --show-toplevel)" && (cd "$REPO_ROOT/apps/platform" && ./vendor/bin/sail artisan test --compact tests/Feature/Artifacts/FindingArtifactSourceTaxonomyTest.php tests/Feature/Artifacts/EvidenceSnapshotSourceTaxonomyTest.php tests/Feature/Artifacts/StoredReportSourceTaxonomyTest.php tests/Feature/Artifacts/InventoryArtifactTypeTaxonomyTest.php tests/Feature/Filament/Artifacts/ArtifactSourceTaxonomySurfaceTest.php tests/Feature/Guards/ArtifactSourceProviderTruthGuardTest.php).
  • T027 [P] Run export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && REPO_ROOT="$(git rev-parse --show-toplevel)" && (cd "$REPO_ROOT/apps/platform" && ./vendor/bin/sail artisan test --compact tests/Browser/Spec284ArtifactSourceTaxonomySmokeTest.php).
  • T028 [P] Run export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && REPO_ROOT="$(git rev-parse --show-toplevel)" && (cd "$REPO_ROOT/apps/platform" && ./vendor/bin/sail bin pint --dirty --format agent).
  • T029 [P] Review touched files to confirm Filament v5 and Livewire v4 compliance, provider registration staying in apps/platform/bootstrap/providers.php, truthful global-search posture, unchanged asset strategy, no new artifact table, no detector catalog, no package runtime, no historical backfill, and Specs 285 through 287 remaining deferred.

Dependencies & Execution Order

Phase Dependencies

  • Phase 0 (External Gate): no dependencies; complete before implementation starts.
  • Phase 1 (Setup): depends on Phase 0.
  • Phase 2 (Foundational): depends on Phase 1 and blocks all story work.
  • Phase 3 (US1): depends on Phase 2 and establishes the canonical descriptor for findings, evidence, and stored reports.
  • Phase 4 (US2): depends on Phase 2 and should land with or immediately after US1 so inventory type semantics align with the shared descriptor vocabulary.
  • Phase 5 (US3): depends on US1 and US2 because operator-facing surfaces should consume the final descriptor and inventory split.
  • Phase 6 (US4): depends on US1 through US3 so downstream shared consumers inherit the final vocabulary instead of an intermediate mapping.
  • Phase 7 (Polish): depends on all desired user stories being complete.

User Story Dependencies

  • US1 (P1): independently testable after Phase 2 and is the first required implementation increment.
  • US2 (P1): independently testable after Phase 2, but should ship after or with US1 because inventory should not introduce parallel artifact-type language.
  • US3 (P2): independently testable after US1 and US2 once the shared descriptor is stable.
  • US4 (P3): independently testable after US1 through US3 and closes the remaining source_family drift in touched shared consumers.

Within Each User Story

  • Write or extend the listed Pest coverage first and make it fail for the intended gap.
  • Apply the smallest shared-seam changes needed to satisfy the story without reopening Specs 285 through 287.
  • Re-run the narrowest relevant validation command for that story before moving to the next story.

Parallel Execution Examples

  • Setup: T002 through T006 can run in parallel once T000 and T001 set the bounded scope.
  • Foundational: T007 through T011 can run in parallel before T012 converges the canonical descriptor seam.
  • US1: T013 can run alongside implementation prep; T014 through T016 should merge serially around finding, evidence, and stored-report seams.
  • US2: T017 can run alongside T018, then T019 follows once the inventory type split is stable.
  • US3: T020 can run alongside implementation prep; T021 and T022 should merge serially around shared presenter files.
  • US4: T023 can run alongside T024 because both touch bounded shared-consumer alignment only.
  • Polish: T025 through T028 can run in parallel after implementation is complete; T029 closes the bounded-scope review last.

Implementation Strategy

Suggested MVP Scope

  • MVP = US1 + US2. Land the shared descriptor and inventory type split first so later surface cleanup does not build on inconsistent underlying semantics.

Incremental Delivery

  1. Complete Phase 0, Phase 1, and Phase 2.
  2. Deliver US1 so findings, evidence, and stored reports stop depending on Microsoft-only top-level summary nouns.
  3. Deliver US2 so inventory type semantics stop teaching policy_type as universal truth.
  4. Deliver US3 so operator-facing surfaces visibly converge on the final descriptor-first disclosure.
  5. Deliver US4 only if touched support or AI consumers need explicit alignment.
  6. Finish with the exact validation commands and the final bounded-scope review in Phase 7.

Team Strategy

  1. Parallelize the failing test work first.
  2. Serialize merges around the shared descriptor seam, evidence providers, and Filament resource presenters to avoid contract-shape conflicts.
  3. Reject any implementation branch that introduces a detector catalog, package runtime, backfill work, a provider framework, or adjacent copy or RBAC scope.

Deferred Follow-Ups / Non-Goals

  • Spec 285 workspace-first RBAC and environment-access scoping
  • Spec 286 broader UI copy, IA, and localization neutralization
  • Spec 287 cutover quality gates and no-legacy enforcement
  • package runtime or package-output surfaces beyond the optional package_run_id contract slot
  • detector catalog or broader control-catalog expansion