194 lines
18 KiB
Markdown
194 lines
18 KiB
Markdown
---
|
|
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.
|
|
|
|
- [x] 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.
|
|
- [x] 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.
|
|
- [x] 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.
|
|
|
|
- [x] 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`.
|
|
- [x] 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.
|
|
- [x] 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.
|
|
|
|
- [x] 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.
|
|
- [x] 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`.
|
|
- [x] 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`.
|
|
- [x] 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.
|
|
|
|
- [x] 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.
|
|
- [x] 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`.
|
|
- [x] 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.
|
|
- [x] 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.
|
|
|
|
- [x] 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.
|
|
- [x] 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.
|
|
- [x] 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.
|
|
|
|
- [x] 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.
|
|
- [x] 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`.
|
|
- [x] 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`.
|
|
- [x] 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
|
|
|
|
1. Complete Phase 1 and Phase 2 to lock the package-local artifact structure and reviewer flow.
|
|
2. Deliver US1 by building the full cue inventory and category classification.
|
|
3. Deliver US2 by assigning dispositions, producing the follow-up map, and syncing the candidate or roadmap references.
|
|
4. Deliver US3 by distilling the standards delta into the package and `docs/ui/tenantpilot-enterprise-ui-standards.md`.
|
|
5. Finish with Phase 6 validation and explicit preparation close-out.
|
|
|
|
### Team Strategy
|
|
|
|
1. Keep the package-local documents as the main working surface and avoid application-code edits entirely.
|
|
2. Parallelize corpus review and audit drafting where tasks touch different repository artifacts.
|
|
3. 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/` |