ahmido bf561b867c Automated: commit from 278-cross-domain-indicator-audit (#334 )

Automated PR created by Copilot: includes all local changes.

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #334

2026-05-06 09:21:06 +00:00

18 KiB

Raw Blame History

description
Task list for Cross-Domain Progress Indicator Semantics Audit

Tasks: Cross-Domain Progress Indicator Semantics Audit

Input: Design documents from specs/278-cross-domain-indicator-audit/
Prerequisites: specs/278-cross-domain-indicator-audit/spec.md, specs/278-cross-domain-indicator-audit/plan.md, specs/278-cross-domain-indicator-audit/checklists/requirements.md, specs/278-cross-domain-indicator-audit/research.md, specs/278-cross-domain-indicator-audit/data-model.md, specs/278-cross-domain-indicator-audit/quickstart.md, specs/278-cross-domain-indicator-audit/contracts/cross-domain-indicator-audit.logical.openapi.yaml

Review Artifact: specs/278-cross-domain-indicator-audit/checklists/requirements.md is the outcome-of-record for the review outcome class, workflow outcome, and test-governance outcome. If implementation widens into shared indicator components, runtime contract code, presenter refactors, migrations, analytics, score recalculation, quality-gate code, or domain cleanup beyond inventory/classification and documented follow-up recommendations, update that artifact and resolve the spillover as split or reject-or-split before continuing.

Tests: No runtime tests. Keep proof in repository-artifact review plus focused diff-check and rg validation only. Operations: No OperationRun, queue, remote call, or background processing is introduced. RBAC: No membership, capability, route, or panel-access behavior changes are allowed. Record scope, audience, and leakage risks as audit metadata only. Shared Pattern Reuse: Treat docs/ui/tenantpilot-enterprise-ui-standards.md, docs/product/spec-candidates.md, docs/product/roadmap.md, and the named presenter/widget/service anchors as inventory sources only. Do not rewrite runtime surfaces in this slice. Filament / Panel Guardrails: Filament remains v5 on Livewire v4. Provider registration remains unchanged in apps/platform/bootstrap/providers.php. No globally searchable resource, destructive action, or asset-strategy change is allowed. Organization: Tasks are grouped by user story so inventory/classification, follow-up mapping, and standards-delta work remain separate docs-governance increments with explicit reviewer checkpoints. Review Outcome: acceptable-special-case Workflow Outcome: keep Test-governance Outcome: keep

Test Governance Checklist

N/A Runtime lanes remain unchanged; proof stays in review and diff-check only.
N/A No Pest, browser, or heavy-governance test family is added because no runtime behavior changes.
N/A No fixtures, helpers, factories, seeds, or support defaults change because no application or test files are touched.
N/A Surface-profile coverage remains docs-only; no operator-facing runtime surface is implemented here.
N/A Planned validation commands cover only the spec package plus bounded documentation targets.
N/A Any drift into runtime implementation resolves as reject-or-split, not as silent scope expansion.

Phase 1: Setup (Shared Context)

Purpose: Lock the bounded audit corpus, package-local output targets, and outcome-of-record handling before repository-doc edits begin.

T001 Review specs/278-cross-domain-indicator-audit/spec.md, specs/278-cross-domain-indicator-audit/plan.md, specs/278-cross-domain-indicator-audit/research.md, specs/278-cross-domain-indicator-audit/data-model.md, specs/278-cross-domain-indicator-audit/quickstart.md, specs/278-cross-domain-indicator-audit/checklists/requirements.md, and specs/278-cross-domain-indicator-audit/contracts/cross-domain-indicator-audit.logical.openapi.yaml together so the slice stays docs-only, inventory-first, and explicitly split from runtime work.
T002 [P] Confirm the bounded source corpus in docs/ui/tenantpilot-enterprise-ui-standards.md, docs/product/spec-candidates.md, docs/product/roadmap.md, apps/platform/app/Support/OpsUx/OperationUxPresenter.php, apps/platform/app/Filament/Widgets/Inventory/InventoryKpiHeader.php, apps/platform/app/Filament/Widgets/Dashboard/RecoveryReadiness.php, apps/platform/app/Services/Baselines/SnapshotRendering/BaselineSnapshotPresenter.php, apps/platform/app/Services/ReviewPackService.php, and apps/platform/app/Support/TenantDashboard/TenantDashboardSummaryBuilder.php so later inventory work uses repo truth only.
T003 Create specs/278-cross-domain-indicator-audit/inventory.md, specs/278-cross-domain-indicator-audit/follow-up-map.md, and specs/278-cross-domain-indicator-audit/standards-delta.md as the package-local audit outputs referenced by later story work.

Phase 2: Foundational (Blocking Prerequisites)

Purpose: Translate the prep artifacts into concrete audit schemas and reviewer rules before any user-story drafting begins.

Critical: No user-story work should begin until these package-local schemas and validation boundaries are in place.

T004 [P] Translate the Indicator Inventory Entry, Recommendation Disposition, Standards Delta Rule, and Follow-Up Map Entry fields from specs/278-cross-domain-indicator-audit/data-model.md and specs/278-cross-domain-indicator-audit/contracts/cross-domain-indicator-audit.logical.openapi.yaml into concrete section or table templates inside specs/278-cross-domain-indicator-audit/inventory.md, specs/278-cross-domain-indicator-audit/follow-up-map.md, and specs/278-cross-domain-indicator-audit/standards-delta.md.
T005 [P] Update specs/278-cross-domain-indicator-audit/quickstart.md with the concrete reviewer flow for specs/278-cross-domain-indicator-audit/inventory.md, specs/278-cross-domain-indicator-audit/follow-up-map.md, and specs/278-cross-domain-indicator-audit/standards-delta.md, keeping proof in docs-only validation.
T006 Update specs/278-cross-domain-indicator-audit/plan.md and specs/278-cross-domain-indicator-audit/checklists/requirements.md so the review outcome fields and scope guardrails mention the concrete package outputs and restate the reject-or-split boundary for any runtime spillover.

Checkpoint: The audit bundle shape, review artifact, and reviewer flow are fixed before cue-by-cue work begins.

Phase 3: User Story 1 - Classify existing indicator cues (Priority: P1)

Goal: Build one repo-based inventory that states what each in-scope indicator-like cue actually measures.

Independent Test: Review specs/278-cross-domain-indicator-audit/inventory.md against the named repo anchors and the bounded search results, then confirm every cue has exactly one entry with source path, visible pattern, data basis, category, determinism, scope, likely reading, and risk note.

T007 [P] [US1] Inventory the named cue sources in apps/platform/app/Support/OpsUx/OperationUxPresenter.php, apps/platform/app/Filament/Widgets/Inventory/InventoryKpiHeader.php, apps/platform/app/Filament/Widgets/Dashboard/RecoveryReadiness.php, apps/platform/app/Services/Baselines/SnapshotRendering/BaselineSnapshotPresenter.php, apps/platform/app/Services/ReviewPackService.php, and apps/platform/app/Support/TenantDashboard/TenantDashboardSummaryBuilder.php into specs/278-cross-domain-indicator-audit/inventory.md, recording one row per visible cue with source path, surface, domain, visible cue, visual pattern, data source, and calculation basis.
T008 [P] [US1] Run bounded repository search from apps/platform/app/ and apps/platform/resources/views/filament/ to capture additional in-scope indicator-like cues and append only the confirmed entries to specs/278-cross-domain-indicator-audit/inventory.md.
T009 [US1] Classify every entry in specs/278-cross-domain-indicator-audit/inventory.md with exactly one semantic category, determinism, scope mode, audience mode, likely user reading, and misunderstanding risk using the allowed values from specs/278-cross-domain-indicator-audit/data-model.md.
T010 [US1] Reconcile specs/278-cross-domain-indicator-audit/inventory.md, specs/278-cross-domain-indicator-audit/spec.md, and specs/278-cross-domain-indicator-audit/contracts/cross-domain-indicator-audit.logical.openapi.yaml so the inventory covers the named anchors, preserves the docs-only boundary, and contains no duplicate or unclassified cues.

Checkpoint: The package has one bounded, fully classified inventory of existing indicator-like cues.

Phase 4: User Story 2 - Prepare bounded follow-up work (Priority: P1)

Goal: Map every risky or ambiguous cue to one bounded next lane so future runtime work does not need to repeat discovery or collapse into a single cleanup program.

Independent Test: Inspect specs/278-cross-domain-indicator-audit/inventory.md and specs/278-cross-domain-indicator-audit/follow-up-map.md, then confirm every non-keep as-is cue has exactly one disposition and, when required, exactly one follow-up lane.

T011 [P] [US2] Add one disposition and, when required, one follow-up lane to each entry in specs/278-cross-domain-indicator-audit/inventory.md, keeping keep as-is as the only lane-less disposition.
T012 [US2] Materialize the grouped follow-up ownership in specs/278-cross-domain-indicator-audit/follow-up-map.md for the five required lanes: standards patch lane, metric/indicator contract foundation, shared indicator component system, quality gate lane, and domain migration lane.
T013 [P] [US2] Update docs/product/spec-candidates.md with the bounded follow-up candidates and seed questions sourced from specs/278-cross-domain-indicator-audit/follow-up-map.md, keeping contract, component, quality-gate, and migration work as separate candidates.
T014 [P] [US2] Update docs/product/roadmap.md only where specs/278-cross-domain-indicator-audit/follow-up-map.md changes sequencing or dependency notes, preserving this audit as the current docs-first slice and leaving related runtime specs context-only.

Checkpoint: Every risky or ambiguous cue now points to one bounded follow-up lane instead of a vague cleanup bucket.

Phase 5: User Story 3 - Feed future standards review consistently (Priority: P2)

Goal: Produce one standards-delta layer above individual domains so future indicator proposals can be reviewed against shared product language.

Independent Test: Review specs/278-cross-domain-indicator-audit/standards-delta.md and docs/ui/tenantpilot-enterprise-ui-standards.md, then confirm they define the allowed categories, determinate-progress rules, wording constraints, dashboard constraints, provider-boundary notes, and anti-patterns without implying runtime implementation in this slice.

T015 [P] [US3] Derive specs/278-cross-domain-indicator-audit/standards-delta.md from specs/278-cross-domain-indicator-audit/inventory.md and specs/278-cross-domain-indicator-audit/follow-up-map.md, covering allowed categories, determinate-progress eligibility, freshness or direction rules, customer-safe wording, dashboard constraints, provider-boundary notes, and forbidden anti-patterns.
T016 [US3] Update docs/ui/tenantpilot-enterprise-ui-standards.md with the bounded indicator-semantics delta from specs/278-cross-domain-indicator-audit/standards-delta.md without copying the full inventory or introducing runtime implementation commitments.
T017 [US3] Align specs/278-cross-domain-indicator-audit/research.md and specs/278-cross-domain-indicator-audit/quickstart.md with the finished standards-delta and follow-up ownership so later reviewers and spec authors can reuse this package without repeating cross-repo discovery.

Checkpoint: The package now has a durable standards-delta layer and reviewer handoff above individual domains.

Phase 6: Polish & Cross-Cutting Validation

Purpose: Reconcile review outcomes, run the canonical docs-only validation commands, and prove the slice stayed out of application code.

T018 [P] Update specs/278-cross-domain-indicator-audit/checklists/requirements.md, specs/278-cross-domain-indicator-audit/plan.md, and specs/278-cross-domain-indicator-audit/quickstart.md with the final review outcome class, workflow outcome, test-governance outcome, actual artifact paths, and any explicit reject-or-split note for runtime spillover.
T019 [P] Run export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && git diff --check -- specs/278-cross-domain-indicator-audit/spec.md specs/278-cross-domain-indicator-audit/plan.md specs/278-cross-domain-indicator-audit/research.md specs/278-cross-domain-indicator-audit/data-model.md specs/278-cross-domain-indicator-audit/quickstart.md specs/278-cross-domain-indicator-audit/checklists/requirements.md specs/278-cross-domain-indicator-audit/contracts/cross-domain-indicator-audit.logical.openapi.yaml specs/278-cross-domain-indicator-audit/tasks.md specs/278-cross-domain-indicator-audit/inventory.md specs/278-cross-domain-indicator-audit/follow-up-map.md specs/278-cross-domain-indicator-audit/standards-delta.md docs/ui/tenantpilot-enterprise-ui-standards.md docs/product/spec-candidates.md docs/product/roadmap.md.
T020 [P] Run export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && git diff -- specs/278-cross-domain-indicator-audit docs/ui/tenantpilot-enterprise-ui-standards.md docs/product/spec-candidates.md docs/product/roadmap.md and export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && rg -n -- "standards patch lane|metric/indicator contract foundation|shared indicator component system|quality gate lane|domain migration lane" specs/278-cross-domain-indicator-audit/spec.md specs/278-cross-domain-indicator-audit/plan.md specs/278-cross-domain-indicator-audit/research.md specs/278-cross-domain-indicator-audit/data-model.md specs/278-cross-domain-indicator-audit/quickstart.md specs/278-cross-domain-indicator-audit/checklists/requirements.md specs/278-cross-domain-indicator-audit/tasks.md specs/278-cross-domain-indicator-audit/inventory.md specs/278-cross-domain-indicator-audit/follow-up-map.md specs/278-cross-domain-indicator-audit/standards-delta.md docs/ui/tenantpilot-enterprise-ui-standards.md docs/product/spec-candidates.md docs/product/roadmap.md.
T021 Review the final diff to confirm no files under apps/platform/ or apps/platform/tests/ changed for implementation purposes and record final preparation-validation completion in specs/278-cross-domain-indicator-audit/checklists/requirements.md.

Dependencies & Execution Order

Phase Dependencies

Phase 1 (Setup): no dependencies; start immediately.
Phase 2 (Foundational): depends on Phase 1 and blocks all user-story work.
Phase 3 (US1): depends on Phase 2 because classification requires the concrete audit templates and reviewer flow.
Phase 4 (US2): depends on US1 because dispositions and follow-up lanes require the completed inventory.
Phase 5 (US3): depends on US1 and US2 because the standards delta should reflect both the classified cues and their bounded follow-up ownership.
Phase 6 (Polish): depends on all desired stories being complete.

User Story Dependencies

US1 (P1): first independently reviewable increment once the package-local audit templates are in place.
US2 (P1): depends on US1 and becomes independently reviewable once every classified cue has one bounded disposition and follow-up lane.
US3 (P2): depends on US1 and US2 and becomes independently reviewable once the shared standards delta lands in both the package and the standards document.

Within Each User Story

Finish the concrete artifact scaffolding before cue-level editing begins.
Keep all edits inside specs/278-cross-domain-indicator-audit/, docs/ui/tenantpilot-enterprise-ui-standards.md, docs/product/spec-candidates.md, and docs/product/roadmap.md.
Treat application files under apps/platform/ as evidence sources only, not as implementation targets.
Re-run the narrowest docs-only validation command after each story checkpoint before moving on.

Parallel Execution Examples

Phase 1

T002 and T003 can run in parallel after T001 confirms the bounded slice.

Phase 2

T004 and T005 can run in parallel once T003 creates the package-local output files.

User Story 1

T007 and T008 can run in parallel because one inventories the named anchors while the other handles bounded repo search.

User Story 2

T013 and T014 can run in parallel once T011 and T012 establish the final follow-up-lane map.

User Story 3

T016 and T017 can run in parallel once T015 finishes the package-local standards delta.

Polish

T019 and T020 can run in parallel after T018 finalizes the review and outcome fields.

Implementation Strategy

Suggested MVP Scope

MVP = US1 + US2. The audit becomes actionable once the product has both the classified inventory and the bounded follow-up map. US3 can then land as the shared standards-review layer.

Incremental Delivery

Complete Phase 1 and Phase 2 to lock the package-local artifact structure and reviewer flow.
Deliver US1 by building the full cue inventory and category classification.
Deliver US2 by assigning dispositions, producing the follow-up map, and syncing the candidate or roadmap references.
Deliver US3 by distilling the standards delta into the package and docs/ui/tenantpilot-enterprise-ui-standards.md.
Finish with Phase 6 validation and explicit preparation close-out.

Team Strategy

Keep the package-local documents as the main working surface and avoid application-code edits entirely.
Parallelize corpus review and audit drafting where tasks touch different repository artifacts.
Serialize merges around docs/ui/tenantpilot-enterprise-ui-standards.md, docs/product/spec-candidates.md, and docs/product/roadmap.md because those files are likely conflict hotspots.

Explicit Non-Goals

runtime shared indicator component implementation
runtime metric or indicator contract code
migrations, persistence changes, or score recalculation
presenter or widget refactors beyond using them as audit evidence
analytics, charting, or quality-gate code
broad domain cleanup outside inventory/classification and documented follow-up recommendations
application or test changes under apps/platform/

18 KiB Raw Blame History