107 lines
8.8 KiB
Markdown
107 lines
8.8 KiB
Markdown
# Specification Quality Checklist: Provider-neutral Artifact Source Taxonomy
|
|
|
|
**Purpose**: Validate package completeness, boundedness, and readiness before implementation
|
|
**Created**: 2026-05-08
|
|
**Feature**: [spec.md](../spec.md)
|
|
|
|
## Content Quality
|
|
|
|
- [x] The package stays on reserved slot `284` and does not silently absorb work from Specs `285` through `287`.
|
|
- [x] The package explicitly documents one shared artifact-source descriptor over existing persisted truth and does not introduce a new artifact table or ledger.
|
|
- [x] The package pins the exact `source_family`, `source_kind`, and `source_target_kind` inventories instead of leaving them implicit.
|
|
- [x] The package makes the inventory `canonical_type` / `provider_object_type` / `provider_display_type` split explicit.
|
|
- [x] The package explicitly rejects a detector catalog, package runtime, control-catalog expansion, and historical backfill.
|
|
- [x] `plan.md`, `research.md`, `data-model.md`, `quickstart.md`, and the logical contract all describe the same bounded slice.
|
|
|
|
## Requirement Completeness
|
|
|
|
- [x] No `[NEEDS CLARIFICATION]` markers remain in `spec.md`, `plan.md`, `research.md`, `data-model.md`, or `quickstart.md`.
|
|
- [x] Requirements remain testable and bounded to current artifact families and current operator surfaces.
|
|
- [x] The descriptor fields, inventory split, and no-backfill posture are explicit across the package.
|
|
- [x] The exact `source_family`, `source_kind`, and `source_target_kind` inventories are pinned identically across `spec.md`, `plan.md`, `research.md`, `data-model.md`, `quickstart.md`, `tasks.md`, the logical contract, and this checklist.
|
|
- [x] `package_run_id` is explicitly optional and does not imply package runtime in the current release.
|
|
- [x] Reviewer flow and proof guidance explicitly cover `workspace_id`, `tenant_id`, `managed_environment_id`, `provider_connection_id`, and `source_target_identifier` semantics when available.
|
|
- [x] Scope boundaries, assumptions, risks, and deferred adjacent candidates remain explicit.
|
|
|
|
## Repo Truth Anchoring
|
|
|
|
- [x] The package reflects that `Finding` already persists `finding_type`, optional `source`, and `evidence_jsonb`.
|
|
- [x] The package reflects that `EvidenceSourceProvider` and `EvidenceSnapshotItem` currently stop at `source_kind`, raw record type, and raw record id.
|
|
- [x] The package reflects that `StoredReport` already persists `report_type` while current report producers already place `provider_key` inside payload.
|
|
- [x] The package reflects that `InventoryItem` and `InventoryPolicyTypeMeta` still rely on `policy_type` as current inventory artifact detail.
|
|
- [x] The package reflects that `FindingsSummarySource` currently hardcodes Microsoft-facing detector and workload logic while still resolving canonical controls.
|
|
- [x] The package reflects that current support or AI governed bundles already use `source_family` as a naming precedent without yet solving artifact lineage.
|
|
|
|
## Feature Readiness
|
|
|
|
- [x] Filament v5 and Livewire v4 expectations remain explicit across the package.
|
|
- [x] Provider registration location remains explicit as `apps/platform/bootstrap/providers.php`.
|
|
- [x] Global-search posture remains explicit for `FindingResource`, `InventoryItemResource`, `EvidenceSnapshotResource`, `StoredReportResource`, and `TenantReviewResource`.
|
|
- [x] The package explicitly states that no new destructive action is introduced and that existing action confirmation or authorization rules remain unchanged.
|
|
- [x] The unchanged asset strategy remains explicit.
|
|
- [x] Specs `281`, `282`, and `283` are recorded as already-present prerequisites in current repo truth.
|
|
|
|
## Artifact Alignment
|
|
|
|
- [x] `research.md` records the same bounded descriptor decisions reflected in `plan.md`.
|
|
- [x] `data-model.md` models the same descriptor fields, pinned inventories, inventory type split, and legacy-read rules reflected in the spec and plan.
|
|
- [x] `quickstart.md` restates the same reviewer flow, pinned inventories, and proof commands used by `spec.md` and `plan.md`.
|
|
- [x] `contracts/provider-neutral-artifact-source-taxonomy.logical.openapi.yaml` models the same logical GET surfaces and descriptor-first view models described in the plan.
|
|
- [x] Canonical proof commands are pinned identically across `spec.md`, `plan.md`, `quickstart.md`, and `tasks.md`, and this checklist explicitly references that pinned command set.
|
|
|
|
## Pinned 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`
|
|
|
|
## Pinned Proof Commands
|
|
|
|
```bash
|
|
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)
|
|
```
|
|
|
|
```bash
|
|
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)
|
|
```
|
|
|
|
```bash
|
|
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)
|
|
```
|
|
|
|
```bash
|
|
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)
|
|
```
|
|
|
|
## Test Governance
|
|
|
|
- [x] Planned proof stays bounded to focused unit tests, feature tests, one guard test, and one browser smoke.
|
|
- [x] No new heavy-governance family or broad browser matrix is introduced.
|
|
- [x] Workspace, managed-environment, finding, evidence, stored-report, review, and inventory fixture cost is acknowledged instead of hidden.
|
|
- [x] Reviewer handoff includes exact minimal validation commands and concrete stop questions.
|
|
|
|
## Notes
|
|
|
|
- Reviewed against `.specify/memory/constitution.md`, `docs/product/spec-candidates.md`, `docs/product/roadmap.md`, `specs/279-workspace-managed-environment-core/spec.md`, `specs/281-provider-connection-scope/spec.md`, `specs/282-governance-artifact-retargeting/spec.md`, `specs/283-provider-capability-registry/spec.md`, `apps/platform/app/Models/Finding.php`, `apps/platform/app/Models/EvidenceSnapshotItem.php`, `apps/platform/app/Models/StoredReport.php`, `apps/platform/app/Models/InventoryItem.php`, `apps/platform/app/Services/Evidence/Contracts/EvidenceSourceProvider.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/Services/EntraAdminRoles/EntraAdminRolesReportService.php`, `apps/platform/app/Support/Inventory/InventoryPolicyTypeMeta.php`, `apps/platform/app/Support/Governance/Controls/CanonicalControlResolutionRequest.php`, `apps/platform/app/Services/TenantReviews/TenantReviewSectionFactory.php`, `apps/platform/app/Support/SupportDiagnostics/SupportDiagnosticBundleBuilder.php`, `apps/platform/app/Support/Ai/AiUseCaseCatalog.php`, `apps/platform/app/Filament/Resources/FindingResource.php`, `apps/platform/app/Filament/Resources/EvidenceSnapshotResource.php`, `apps/platform/app/Filament/Resources/InventoryItemResource.php`, `apps/platform/app/Filament/Resources/StoredReportResource.php`, and `apps/platform/app/Filament/Resources/TenantReviewResource.php` on 2026-05-08.
|
|
- No application implementation, test execution, or runtime validation was performed while preparing this package.
|
|
|
|
## Review Outcome
|
|
|
|
- **Outcome class**: `implementation-ready`
|
|
- **Workflow outcome**: `keep`
|
|
- **Test-governance outcome**: `keep`
|
|
- **Reason**: The prior SCOPE-001 implementation block is resolved by current repo truth and Spec `279`'s approved managed-environment core exception. Runtime work may proceed because the slice still derives provider-neutral artifact lineage and inventory type semantics from already scoped artifact records without adding a new artifact table, descriptor columns, detector catalog, backfill work, ownership plane, or adjacent package-runtime scope.
|