ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
bcabb14480
TenantAtlas/specs/260-governance-service-packaging/tasks.md
ahmido bcabb14480 commit alles (automatisch) → platform-dev (#315) 
Automatisch erstellt: Commit aller Änderungen in Branch 260-governance-service-packaging-session-1777640889.
Bitte prüfen und mergen.

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #315
2026-05-01 14:38:09 +00:00

25 KiB
Raw Blame History

description
Task list for Governance-as-a-Service Packaging v1

Tasks: Governance-as-a-Service Packaging v1

Input: Design documents from specs/260-governance-service-packaging/
Prerequisites: specs/260-governance-service-packaging/plan.md (required), specs/260-governance-service-packaging/spec.md (required), specs/260-governance-service-packaging/research.md, specs/260-governance-service-packaging/data-model.md, specs/260-governance-service-packaging/quickstart.md, specs/260-governance-service-packaging/contracts/governance-service-packaging.openapi.yaml

Tests: REQUIRED (Pest). Keep proof in the existing Unit, Feature, and one bounded Browser smoke family only; do not add a new heavy-governance, report-engine, or package-specific browser suite for this read-only packaging slice. Operations: No new OperationRun, queue start, retry flow, report-generation run, scheduling, batching, or campaign orchestration is introduced. The package path must reuse existing released-review truth and current signed review-pack download behavior only. RBAC: Workspace membership remains the first 404 boundary; tenant or review scope mismatches remain 404; the reused released-review detail route and in-scope secondary artifact access may still return inherited 403 capability denials. Reuse apps/platform/app/Support/Auth/Capabilities.php and apps/platform/app/Services/Auth/RoleCapabilityMap.php; do not introduce raw capability strings or role-name checks. Shared Pattern Reuse: Reuse CustomerReviewWorkspace, TenantReviewResource, ViewTenantReview, TenantReviewComposer, TenantReviewSectionFactory, ComplianceEvidenceMappingV1, ReviewPackService, ReviewPackDownloadController, ArtifactTruthPresenter, the current evidence-resource seams, localization files, and the shared audit path. No new GovernancePackage domain, report engine, stored-report viewer shell, AI summary layer, or parallel package workflow is allowed. Filament / Panel Guardrails: Filament remains v5 on Livewire v4. Provider registration remains unchanged in apps/platform/bootstrap/providers.php. apps/platform/app/Filament/Resources/TenantReviewResource.php, apps/platform/app/Filament/Resources/ReviewPackResource.php, and apps/platform/app/Filament/Resources/EvidenceSnapshotResource.php remain globally disabled. No new panel, provider, destructive package action, or asset strategy change is allowed. Organization: Tasks are grouped by user story so package entry, management-ready meaning, and audit or isolation behavior remain independently testable while the implementation stays bounded to one on-demand package for one released review context.

Test Governance Checklist

  • Lane assignment stays confidence plus the existing bounded browser smoke and remains the narrowest sufficient proof for this slice.
  • New or changed tests stay in existing apps/platform/tests/Unit/TenantReview/, apps/platform/tests/Feature/Reviews/, apps/platform/tests/Feature/TenantReview/, apps/platform/tests/Feature/ReviewPack/, apps/platform/tests/Feature/Evidence/, and apps/platform/tests/Browser/Reviews/ families only.
  • Shared helpers, fixtures, membership setup, released-review fixtures, review-pack fixtures, evidence snapshots, and decision fixtures stay cheap by default; no queue or provider-sync setup is added.
  • Planned validation commands cover package derivation, package access, auditability, and rendered disclosure without widening into unrelated lanes.
  • The declared surface test profile stays shared-detail-family for the released-review detail and standard-native-filament for the workspace page.
  • Browser work stays bounded to the existing apps/platform/tests/Browser/Reviews/CustomerReviewWorkspaceSmokeTest.php family only.
  • Any drift toward new package persistence, report engines, scheduling, campaigns, stored-report viewer productization, or broader governance-inbox semantics resolves as reject-or-split or follow-up-spec, not hidden implementation growth.

Phase 1: Setup (Shared Context)

Purpose: Confirm the current review, package, interpretation, localization, audit, and authorization seams before implementation begins.

  • T001 Review specs/260-governance-service-packaging/spec.md, specs/260-governance-service-packaging/plan.md, specs/260-governance-service-packaging/research.md, specs/260-governance-service-packaging/data-model.md, specs/260-governance-service-packaging/quickstart.md, specs/260-governance-service-packaging/contracts/governance-service-packaging.openapi.yaml, specs/258-customer-review-productization/spec.md, and specs/259-compliance-evidence-mapping/spec.md together so the implementation stays anchored to released-review truth and shared interpretation.
  • T002 [P] Confirm the workspace and released-review seams in apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php, apps/platform/resources/views/filament/pages/reviews/customer-review-workspace.blade.php, apps/platform/app/Filament/Resources/TenantReviewResource.php, and apps/platform/app/Filament/Resources/TenantReviewResource/Pages/ViewTenantReview.php.
  • T003 [P] Confirm the existing package-delivery and artifact-truth seams in apps/platform/app/Services/ReviewPackService.php, apps/platform/app/Http/Controllers/ReviewPackDownloadController.php, apps/platform/app/Support/Ui/GovernanceArtifactTruth/ArtifactTruthPresenter.php, and apps/platform/app/Services/TenantReviews/TenantReviewComposer.php.
  • T004 [P] Confirm the localization, audit, and capability seams in apps/platform/lang/en/localization.php, apps/platform/lang/de/localization.php, apps/platform/app/Services/Audit/WorkspaceAuditLogger.php, apps/platform/app/Support/Audit/AuditActionId.php, apps/platform/app/Support/Auth/Capabilities.php, and apps/platform/app/Services/Auth/RoleCapabilityMap.php.

Phase 2: Foundational (Blocking Prerequisites)

Purpose: Lock the shared package derivation, signed-download reuse, copy, and drift-stop rules that every user story depends on.

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

  • T005 [P] Extend apps/platform/tests/Unit/TenantReview/TenantReviewComposerTest.php and apps/platform/tests/Feature/ReviewPack/TenantReviewDerivedReviewPackTest.php to lock package derivation to existing review summary and section truth, without a new GovernancePackage model, persistence table, or report namespace.
  • T006 [P] Extend apps/platform/tests/Feature/TenantReview/TenantReviewExecutivePackTest.php and apps/platform/tests/Feature/ReviewPack/ReviewPackDownloadTest.php to prove the customer-workspace package path reuses downloadCurrentReviewPackAction() and the current signed review-pack download behavior rather than export generation, ReviewPackService::generateFromReview(), or any OperationRun start path.
  • T007 Implement the derived package-summary and package-availability seam inside apps/platform/app/Services/TenantReviews/TenantReviewComposer.php, apps/platform/app/Services/TenantReviews/TenantReviewSectionFactory.php, and apps/platform/app/Support/Ui/GovernanceArtifactTruth/ArtifactTruthPresenter.php without introducing a new packaging service layer, persisted lifecycle, or broader decision framework.
  • T008 [P] Add shared management-ready vocabulary and calm unavailable-state copy in apps/platform/lang/en/localization.php and apps/platform/lang/de/localization.php, keeping the roadmap phrase open decisions narrowed to accepted-risk and exception-decision truth only.
  • T009 [P] Extend apps/platform/tests/Feature/TenantReview/TenantReviewUiContractTest.php and apps/platform/tests/Feature/Reviews/CustomerReviewWorkspacePackAccessTest.php to block drift into a competing workspace package action, operator-only export actions in customer-workspace mode, or a new stored-report viewer shell from the package path.

Checkpoint: Package derivation, signed-download reuse, localized vocabulary, and the main drift-stop guards are in place before surface-specific work starts.

Phase 3: User Story 1 - Produce One Repeatable Stakeholder Package From A Released Review (Priority: P1)

Goal: Give an entitled actor one on-demand package entry for one released review context without starting a new reporting or generation workflow.

Independent Test: Open an eligible released review from the current workspace, confirm the workspace shows package readiness as information only, and confirm the released-review detail reuses the current signed review-pack delivery seam without triggering generation.

Tests for User Story 1

  • T010 [P] [US1] Extend apps/platform/tests/Feature/Reviews/CustomerReviewWorkspacePageTest.php to cover package readiness, management teaser copy, evidence-basis disclosure, calm partial, unavailable, expired, and blocked states, and the absence of a competing package row action.
  • T011 [P] [US1] Extend apps/platform/tests/Feature/Reviews/CustomerReviewWorkspaceLaunchLinksTest.php and apps/platform/tests/Feature/Reviews/CustomerReviewWorkspacePackAccessTest.php to cover released-review launch, package-ready signaling, explicit unavailable-state reasons, governance-package framing over the current export review pack, and signed review-pack reuse from the workspace flow.
  • T012 [P] [US1] Extend apps/platform/tests/Feature/TenantReview/TenantReviewUiContractTest.php and apps/platform/tests/Feature/TenantReview/TenantReviewExecutivePackTest.php to assert one dominant Download governance package action in customer-workspace mode, explicit framing over the current export review pack, and no export-generation fallback when source basis is missing.

Implementation for User Story 1

  • T013 [US1] Update apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php and apps/platform/resources/views/filament/pages/reviews/customer-review-workspace.blade.php to show package readiness, management teaser, evidence basis, and calm unavailable messaging while keeping Open released review as the only dominant action.
  • T014 [US1] Update apps/platform/app/Filament/Resources/TenantReviewResource.php and apps/platform/app/Filament/Resources/TenantReviewResource/Pages/ViewTenantReview.php so the released-review detail owns the package context in customer_workspace=1 mode and reuses downloadCurrentReviewPackAction() instead of exportExecutivePackAction() or any generation path.
  • T015 [US1] Update apps/platform/app/Http/Controllers/ReviewPackDownloadController.php and apps/platform/app/Services/ReviewPackService.php only as needed to carry source-surface, review, tenant-filter, and interpretation metadata through the existing signed download seam without creating a new artifact namespace or package-generation entry point. Repo truth: the existing signed download seam already carried source_surface, review_id, tenant_filter_id, and interpretation_version, so no controller or service code change was required.

Checkpoint: User Story 1 is independently functional when one released review context exposes a repeatable package path that reuses current review-pack truth instead of starting export generation.

Phase 4: User Story 2 - Read Management-Ready Governance Meaning Without Raw Operator Translation (Priority: P1)

Goal: Keep the package management-readable and customer-safe by deriving its meaning from shared interpretation and existing review sections only.

Independent Test: Open one released-review package context and verify that executive summary, top findings, accepted risks, governance decisions, evidence basis, and next action all come from the shared interpretation layer and current review truth, with raw/support detail hidden by default.

Tests for User Story 2

  • T016 [P] [US2] Extend apps/platform/tests/Unit/TenantReview/TenantReviewComposerTest.php to cover management-ready executive summary, top findings, evidence-basis summary, supporting artifact links, and explicit partial states when interpretation truth is incomplete.
  • T017 [P] [US2] Extend apps/platform/tests/Feature/TenantReview/TenantReviewExplanationSurfaceTest.php to cover customer-safe management summary content, hidden raw or support detail by default, and package-summary consistency between released-review detail and supporting artifacts.
  • T018 [P] [US2] Extend apps/platform/tests/Feature/ReviewPack/ReviewPackValidRiskAcceptanceTest.php and apps/platform/tests/Feature/Evidence/ExceptionValidityEvidenceIntegrationTest.php to keep accepted-risk and exception follow-up language narrowed to current governance-decision truth, assert accepted_risks and governance_decisions stay disjoint, and prevent drift into a broader decision inbox or workflow board.

Implementation for User Story 2

  • T019 [US2] Update apps/platform/app/Services/TenantReviews/TenantReviewComposer.php and apps/platform/app/Services/TenantReviews/TenantReviewSectionFactory.php to derive package summary fields from existing control_interpretation, highlights, accepted_risks, and related review section payloads without a new package-local mapper, report engine, or AI summary layer, while keeping stable accepted-risk entries separate from governance-decision follow-up entries.
  • T020 [US2] Update apps/platform/app/Support/Governance/Controls/ComplianceEvidenceMappingV1.php and apps/platform/app/Support/Ui/GovernanceArtifactTruth/ArtifactTruthPresenter.php to keep calm disclosure, package availability messaging, and supporting evidence or review-pack links aligned with shared interpretation and artifact truth, using the canonical mapping publishable -> available, internal_only/stale -> partial, blocked/missing_input -> unavailable, historical_only -> expired, and package-level entitlement restrictions -> blocked, while keeping secondary-proof restrictions on supporting-link disclosure instead of blocking the package summary.
  • T021 [US2] Finalize localized DE and EN management-ready copy in apps/platform/lang/en/localization.php and apps/platform/lang/de/localization.php for executive summary labels, evidence-basis messaging, accepted-risk follow-up, governance-decision wording, and explicit partial, unavailable, expired, and blocked states with truthful stale or entitlement-restricted reasons.

Checkpoint: User Story 2 is independently functional when the same released review shows consistent customer-safe package meaning across workspace summary, released-review detail, and package access without raw operator translation.

Phase 5: User Story 3 - Trust Packaging Boundaries, Auditability, And Scope Isolation (Priority: P2)

Goal: Keep package delivery attributable, tenant-safe, and bounded even when secondary proof access is limited.

Independent Test: Access or download the package for an entitled review, verify current audit coverage, verify explicit secondary-artifact unavailability where needed, and confirm out-of-scope tenant or review targets resolve without leakage.

Tests for User Story 3

  • T022 [P] [US3] Extend apps/platform/tests/Feature/Reviews/CustomerReviewWorkspaceAuthorizationTest.php and apps/platform/tests/Feature/Reviews/CustomerReviewWorkspaceNavigationContextTest.php to cover deny-as-not-found package readiness, tenant-prefilter isolation, and no review, package, report, or evidence hint leakage across tenants.
  • T023 [P] [US3] Extend apps/platform/tests/Feature/TenantReview/TenantReviewUiContractTest.php, apps/platform/tests/Feature/ReviewPack/ReviewPackEntitlementEnforcementTest.php, and apps/platform/tests/Feature/Evidence/EvidenceSnapshotResourceTest.php so the reused released-review detail route can assert inherited in-scope 403 capability denial, while secondary review-pack and evidence links stay capability-gated and the management summary remains readable when only supporting access is restricted.
  • T024 [P] [US3] Extend apps/platform/tests/Feature/TenantReview/TenantReviewAuditLogTest.php and apps/platform/tests/Feature/Evidence/EvidenceSnapshotAuditLogTest.php to assert package access, signed download, and proof opens stay on the current audit infrastructure with source-surface and interpretation-version metadata.

Implementation for User Story 3

  • T025 [US3] Update apps/platform/app/Services/Audit/WorkspaceAuditLogger.php, apps/platform/app/Support/Audit/AuditActionId.php, apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php, and apps/platform/app/Filament/Resources/TenantReviewResource/Pages/ViewTenantReview.php to reuse current audit events and metadata instead of creating a new package audit family. Repo truth: the existing audit action IDs and logger already covered workspace open, tenant-review open, signed pack download, and evidence open with the required metadata, so no new audit family was added.
  • T026 [US3] Keep neutral governance-package framing and secondary artifact disclosure inside apps/platform/app/Filament/Resources/TenantReviewResource/Pages/ViewTenantReview.php, apps/platform/resources/views/filament/pages/reviews/customer-review-workspace.blade.php, and existing evidence or review-pack link surfaces so Download governance package always maps to the current export review pack and no branding or profile-variant system is introduced in v1.
  • T027 [US3] Handle missing, expired, redacted, or unavailable supporting artifacts in apps/platform/app/Support/Ui/GovernanceArtifactTruth/ArtifactTruthPresenter.php, apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php, and apps/platform/app/Filament/Resources/TenantReviewResource/Pages/ViewTenantReview.php so the slice stays explicit about unavailable proof and does not add a stored-report viewer shell, AI summary fallback, schedule, batch, campaign, or broader governance-inbox semantics.

Checkpoint: User Story 3 is independently functional when package access remains attributable, bounded, and tenant-safe without widening the slice into new workflows or surfaces.

Phase 6: Polish & Cross-Cutting Validation

Purpose: Finish focused validation, formatting, and explicit drift checks without widening scope.

  • T028 [P] Run export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/TenantReview/TenantReviewComposerTest.php tests/Feature/Reviews/CustomerReviewWorkspacePageTest.php tests/Feature/Reviews/CustomerReviewWorkspacePackAccessTest.php tests/Feature/Reviews/CustomerReviewWorkspaceLaunchLinksTest.php.
  • T029 [P] Run export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Reviews/CustomerReviewWorkspaceAuthorizationTest.php tests/Feature/Reviews/CustomerReviewWorkspaceNavigationContextTest.php tests/Feature/TenantReview/TenantReviewExplanationSurfaceTest.php tests/Feature/TenantReview/TenantReviewUiContractTest.php tests/Feature/TenantReview/TenantReviewAuditLogTest.php tests/Feature/TenantReview/TenantReviewExecutivePackTest.php tests/Feature/ReviewPack/TenantReviewDerivedReviewPackTest.php tests/Feature/ReviewPack/ReviewPackDownloadTest.php tests/Feature/ReviewPack/ReviewPackEntitlementEnforcementTest.php tests/Feature/ReviewPack/ReviewPackValidRiskAcceptanceTest.php tests/Feature/Evidence/ExceptionValidityEvidenceIntegrationTest.php tests/Feature/Evidence/EvidenceSnapshotResourceTest.php tests/Feature/Evidence/EvidenceSnapshotAuditLogTest.php.
  • T030 [P] Run export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Browser/Reviews/CustomerReviewWorkspaceSmokeTest.php and keep browser work bounded to this existing smoke family only.
  • T031 Run export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent for all touched platform files.
  • T032 [P] Review touched code in apps/platform/app/Services/ReviewPackService.php, apps/platform/app/Http/Controllers/ReviewPackDownloadController.php, apps/platform/app/Services/TenantReviews/TenantReviewComposer.php, and apps/platform/app/Filament/Resources/TenantReviewResource/Pages/ViewTenantReview.php to confirm the package path reuses current review-pack truth and signed download behavior rather than new persistence, export generation, a report engine, an OperationRun, or schedule, batch, or campaign workflows.
  • T033 [P] Review touched code in apps/platform/bootstrap/providers.php, apps/platform/app/Filament/Resources/TenantReviewResource.php, apps/platform/app/Filament/Resources/ReviewPackResource.php, apps/platform/app/Filament/Resources/EvidenceSnapshotResource.php, touched Blade views, and touched localization files to confirm no new panel/provider, global-search surface, asset strategy, stored-report viewer shell, AI summaries, or broader governance-inbox semantics were introduced.

Dependencies & Execution Order

Phase Dependencies

  • Phase 1 (Setup): no dependencies; start immediately.
  • Phase 2 (Foundational): depends on Phase 1 and blocks all user stories.
  • Phase 3 (US1): depends on Phase 2 and establishes the one released-review package entry path.
  • Phase 4 (US2): depends on Phase 2 and should ship with US1 so the package entry path and its management-ready meaning stay aligned.
  • Phase 5 (US3): depends on Phase 2 and is safest after US1 and US2 because audit and isolation checks rely on the package surfaces already existing.
  • Phase 6 (Polish): depends on all desired user stories being complete.

User Story Dependencies

  • US1 (P1): independently testable after Phase 2 and delivers the core on-demand package path for one released review.
  • US2 (P1): independently testable after Phase 2 and should land with US1 so the package does not expose entry without trustworthy management meaning.
  • US3 (P2): independently testable after Phase 2 and hardens auditability, secondary-access handling, and scope isolation after the core path exists.

Within Each User Story

  • Write the listed Pest coverage first for each story and make it fail for the intended gap.
  • Keep implementation inside the existing review, review-pack, interpretation, evidence, localization, and audit seams named in the plan.
  • Re-run the narrowest relevant validation command after each story checkpoint before moving to the next story.

Parallel Execution Examples

Setup / Foundations

  • T002, T003, and T004 can run in parallel during seam confirmation.
  • T005, T006, T008, and T009 can run in parallel before the shared package seam in T007 is finalized.

User Story 1

  • T010, T011, and T012 can run in parallel before runtime edits begin.
  • After the package-entry contract settles, T013 and T015 can proceed in parallel while T014 finalizes the released-review detail surface.

User Story 2

  • T016, T017, and T018 can run in parallel because they cover different aspects of the meaning contract.
  • T019 and T020 can proceed together once the failing tests prove the gap; T021 can land in parallel with the final copy pass.

User Story 3

  • T022, T023, and T024 can run in parallel because they cover authorization, secondary-access, and audit behavior separately.
  • T025 and T026 can proceed together once the package path is stable; T027 should follow to finish the explicit unavailable-state handling.

Implementation Strategy

Suggested MVP Scope

  • MVP = US1 + US2 together. The feature is only product-meaningful when the actor can both reach the package from one released review and trust the management-ready meaning shown there.

Incremental Delivery

  1. Complete Phase 1 and Phase 2.
  2. Deliver US1 and US2 together as the smallest sellable packaging slice.
  3. Add US3 to harden auditability, secondary-access boundaries, and explicit unavailable behavior.
  4. Finish with the focused validation and drift-review tasks in Phase 6.

Team Strategy

  1. Settle the shared package-derivation and signed-download guardrails first.
  2. Parallelize focused tests inside each story before widening implementation.
  3. Serialize merges around CustomerReviewWorkspace, ViewTenantReview, and the shared localization files so the package vocabulary and action hierarchy stay coherent.

Deferred Follow-Ups / Non-Goals

  • Multi-review or multi-tenant package automation stays deferred.
  • Stored-report viewer productization stays deferred unless a repo-real existing viewer seam proves insufficient.
  • Schedule, batch, campaign, PSA, CRM, and customer-communications workflows stay deferred.
  • Package profile variants or broader branding systems stay deferred beyond neutral v1 governance-package framing over the current export review pack.