TenantAtlas/specs/278-cross-domain-indicator-audit/plan.md

Implementation Plan: Cross-Domain Progress Indicator Semantics Audit

Branch: 278-cross-domain-indicator-audit | Date: 2026-05-06 | Spec: spec.md Input: Feature specification from specs/278-cross-domain-indicator-audit/spec.md

Summary

Prepare one repo-governance audit bundle over the product's existing progress-like and indicator-like cues. The narrow implementation path is to inventory current cues from the named repo anchors plus bounded repo search, classify each cue once, record misunderstanding risk and one bounded disposition, derive standards-delta input for docs/ui/tenantpilot-enterprise-ui-standards.md, and map later follow-up work into explicit separate lanes. This slice remains documentation-only. It must not widen into runtime contracts, shared indicator components, quality-gate code, migrations, analytics, charting, score recalculation, or UI rewrites.

Filament remains v5 on Livewire v4, no panel or provider registration change is planned (apps/platform/bootstrap/providers.php remains authoritative), no globally searchable resource changes are involved, no destructive actions are introduced, and no asset registration or filament:assets deployment work is expected.

Inherited Baseline / Explicit Delta

Inherited baseline

• The current UI standard already defines a progress-bar pattern and anti-fake-progress posture.
• Specs 268, 270, 271, and 272 already own OperationRun activity and progress semantics and remain context-only guardrails.
• docs/product/spec-candidates.md and docs/product/roadmap.md already define the candidate queue and roadmap posture for this manual promotion.
• The named runtime anchors already express domain-local truth for execution progress, readiness, coverage, review/export generation, and dashboard summary cues.

Explicit delta in this plan

• create one docs-only indicator inventory schema
• create one docs-only risk, disposition, and follow-up-lane map
• create one standards-delta contract targeted at docs/ui/tenantpilot-enterprise-ui-standards.md
• keep later follow-up work split into separate candidates or specs for the standards patch lane, metric/indicator contract foundation, shared indicator component system, quality gate lane, and domain migration lane
• keep all runtime code, tests, routes, assets, and provider wiring out of scope

Technical Context

Language/Version: Markdown and YAML planning artifacts over PHP 8.4 / Laravel 12 source anchors
Primary Dependencies: spec.md, docs/product/spec-candidates.md, docs/product/roadmap.md, docs/ui/tenantpilot-enterprise-ui-standards.md, nearby Specs 270, 275, and 277, and repo-real source anchors such as OperationUxPresenter, InventoryKpiHeader, RecoveryReadiness, BaselineSnapshotPresenter, ReviewPackService, and TenantDashboardSummaryBuilder
Storage: Repository files only; no database or runtime persistence changes
Testing: Docs/governance review plus focused diff and grep validation; no runtime test lane
Validation Lanes: review, diff-check, grep lane-check
Target Platform: Repo-based prep package under specs/278-cross-domain-indicator-audit/ inside the existing Laravel monorepo
Project Type: Documentation/governance prep package
Performance Goals: reviewers can validate the audit bundle without running the app, and follow-up spec authors do not need to repeat cross-repo discovery
Constraints: no app code changes, no test changes, no migrations, no runtime presenter or component rollout, no analytics or charting, no score recalculation, no domain migration, and no asset, panel, or global-search change
Scale/Scope: one indicator vocabulary, one inventory bundle, one standards-delta bundle, one follow-up map, and one checklist or review outcome set spanning existing operations, dashboard, baseline, review, export, and provider or posture cues only

Likely Affected Repo Surfaces

Prep-package and documentation targets

• 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/contracts/cross-domain-indicator-audit.logical.openapi.yaml
• specs/278-cross-domain-indicator-audit/checklists/requirements.md
• docs/ui/tenantpilot-enterprise-ui-standards.md as the standards-delta destination
• docs/product/spec-candidates.md as the follow-up-candidate sync point for the bounded lanes
• docs/product/roadmap.md as the sequencing reference for the follow-up map posture

Repo-real source anchors to inventory, not rewrite in this slice

• 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
• apps/platform/app/Support/TenantDashboard/TenantDashboardSummaryBuilder.php
• related Blade, widget, or view seams discovered through repo search during the later docs implementation, but still treated as audit inputs only

Filament v5 / Panel Notes

• Livewire v4.0+ compliance: This prep package introduces no runtime Filament or Livewire behavior. Future docs-only implementation of the audit remains compatible with the current Filament v5 + Livewire v4 baseline.
• Provider registration location: No provider or panel registration change is planned. apps/platform/bootstrap/providers.php remains authoritative.
• Global search: No resource or search behavior changes are in scope. This slice must not add, remove, or alter globally searchable resources.
• Destructive actions: None. The audit produces repository artifacts only and must not introduce any action surface.
• Asset strategy: No new asset registration or on-demand loading is planned. Deployment remains unchanged; if later unrelated work registers assets, the normal cd apps/platform && php artisan filament:assets path still applies, but not because of this slice.

Indicator Semantics Audit Fit

• Treat the current repo as the only source corpus. Named presenters, widgets, services, docs, and adjacent specs are evidence, not implementation targets.
• Keep the audit vocabulary documentation-only in this slice. Each cue gets exactly one semantic category, one misunderstanding-risk note, and one bounded disposition.
• Record scope and audience assumptions per cue so future work cannot hide tenant or workspace leakage behind neutral-looking indicators.
• Treat provider-health and permission-posture cues as provider-owned examples inside a neutral platform vocabulary, not as platform-core default semantics.
• Route unresolved cases to separate follow-up specs rather than ad hoc local fixes.

UI / Surface Guardrail Plan

• Guardrail scope: no operator-facing surface change
• Native vs custom classification summary: N/A - this slice does not implement UI
• Shared-family relevance: progress and activity feedback, dashboard signals and cards, KPI rows, readiness blocks, review and evidence summaries, and generation-state cues as audit inputs
• State layers in scope: none
• Audience modes in scope: N/A at runtime; captured as audit metadata only
• Decision/diagnostic/raw hierarchy plan: N/A - current surfaces are documented, not changed
• Raw/support gating plan: N/A
• One-primary-action / duplicate-truth control: the audit may name duplicate-truth risks, but it must not change runtime action hierarchy in this slice
• Handling modes by drift class or surface: report-only now; later runtime adoption becomes review-mandatory per follow-up spec
• Repository-signal treatment: review-mandatory
• Special surface test profiles: N/A
• Required tests or manual smoke: N/A
• Exception path and spread control: any attempt to add runtime components, presenters, migrations, or UI rewrites resolves as reject-or-split
• Active feature PR close-out entry: Guardrail

Shared Pattern & System Fit

• Cross-cutting feature marker: yes
• Systems touched: current UI standards, audit package artifacts, roadmap or candidate docs as follow-up references, and the named runtime anchors as inventory sources
• Shared abstractions reused: existing OperationRun activity-feedback standards, badge semantics, dashboard summary builders, baseline snapshot presentation, review-pack summary logic, and tenant dashboard summary builders as current evidence
• New abstraction introduced? why?: no runtime abstraction. The only new structure is a docs-only audit taxonomy, inventory format, and follow-up map because current repo truth lacks a product-wide semantics layer.
• Why the existing abstraction was sufficient or insufficient: current abstractions are sufficient to express domain-local meaning, but insufficient to state whether visually similar cues across domains mean the same thing.
• Bounded deviation / spread control: none. Ambiguous cues and broad cleanup needs must route to later specs, not hidden runtime work here.

OperationRun UX Impact

• Touches OperationRun start/completion/link UX?: no
• Central contract reused: N/A
• Delegated UX behaviors: N/A
• Surface-owned behavior kept local: N/A
• Queued DB-notification policy: N/A
• Terminal notification path: N/A
• Exception path: none

Provider Boundary & Portability Fit

• Shared provider/platform boundary touched?: yes
• Provider-owned seams: provider health and permission-posture cues, plus provider-specific readiness or access examples found during inventory
• Platform-core seams: indicator vocabulary, category rules, standards-delta language, and future cross-domain review criteria
• Neutral platform terms / contracts preserved: indicator, execution progress, activity state, coverage, completion, health, readiness, risk, pressure, usage, capacity, score, and generation state
• Retained provider-specific semantics and why: provider-specific examples stay labeled as such because they describe provider posture, not generic platform completion or execution truth
• Bounded extraction or follow-up path: follow-up-spec if runtime contract or component work needs deeper provider or platform boundary normalization

Constitution Check

GATE: Must pass before implementation begins and again after the design artifacts are complete.

• Inventory-first / snapshot truth: PASS. The slice only inventories current repo-real cues and does not create a second runtime source of truth.
• Read/write separation: PASS. No write, mutation, or runtime action path is introduced.
• Graph contract path: PASS. No Graph, provider, or remote-call behavior changes are planned.
• Deterministic capabilities: PASS. No capability or authorization logic changes are introduced.
• Workspace and tenant isolation: PASS. The audit records scope assumptions but must not alter route or entitlement behavior.
• RBAC-UX plane separation: PASS. No admin/system plane or tenant-route behavior is changed.
• Destructive confirmation standard: PASS by non-use.
• Global search safety: PASS. No resource or search change enters scope.
• OperationRun / Ops-UX: PASS by non-use. Specs 268, 270, 271, and 272 stay context only.
• Data minimization: PASS. The output is repo documentation only.
• Test governance (TEST-GOV-001): PASS. Proof stays in docs review and focused diff validation with explicit outcome recording.
• Proportionality / no premature abstraction: PASS. The audit vocabulary is docs-only and bounded by explicit follow-up lanes for all runtime work.
• Persisted truth (PERSIST-001): PASS. No new table, entity, projection, or stored runtime artifact is added.
• Behavioral state (STATE-001): PASS. Categories remain documentation-only audit labels in this slice.
• UI semantics / shared pattern first / Filament-native UI: PASS. The slice documents current surfaces and standards gaps without inventing a parallel UI framework.
• Provider boundary (PROV-001): PASS. Mixed seams are named explicitly, and provider-owned examples remain outside platform-core truth.
• Filament / Laravel planning contract: PASS. Filament stays v5 on Livewire v4, provider registration remains in apps/platform/bootstrap/providers.php, and no panel, asset, or global-search change is planned.

Gate evaluation: PASS.

Post-design re-check: PASS. research.md, data-model.md, quickstart.md, contracts/cross-domain-indicator-audit.logical.openapi.yaml, checklists/requirements.md, inventory.md, follow-up-map.md, and standards-delta.md are present and aligned with this docs-only package.

Test Governance Check

• Test purpose / classification by changed surface: N/A - docs and governance only
• Affected validation lanes: review, diff-check, grep lane-check
• Why this lane mix is the narrowest sufficient proof: the package changes only repository artifacts, so structural diff validation and checklist review are the honest proof instead of runtime or browser lanes
• Narrowest implementation proving command(s):

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

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

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

• Fixture / helper / factory / seed / context cost risks: none
• Expensive defaults or shared helper growth introduced?: no
• Heavy-family additions, promotions, or visibility changes: none
• Surface-class relief / special coverage rule: N/A
• Closing validation and reviewer handoff: rerun the exact implementation commands above, verify the package stays docs and governance first, verify the standards-delta target and follow-up lanes are explicit, and verify no runtime contract, component, migration, or app or test edits were pulled into the slice.
• Budget / baseline / trend follow-up: none
• Review-stop questions: did the package stay repo-based and docs-only, are the four future runtime lanes plus the standards patch lane explicit, did any runtime implementation hide inside the plan, and do the validation commands remain identical across the prep artifacts
• Escalation path: reject-or-split for any drift into runtime code, tests, migrations, or UI implementation
• Active feature PR close-out entry: Guardrail
• Why no dedicated follow-up spec is needed: this package is itself the bounded prep artifact; the runtime follow-up lanes remain intentionally separate specs
• Test-governance outcome: keep

Review Checklist Status

• Review checklist artifact: checklists/requirements.md
• Review outcome class: acceptable-special-case
• Workflow outcome: keep
• Test-governance outcome: keep
• Escalation rule: if follow-up implementation derived from this package changes app code, tests, routes, assets, panels, or provider wiring, or if it collapses the follow-up lanes into one broad runtime rewrite, create a separate spec and resolve the spillover as split or reject-or-split before continuing

Rollout & Risk Controls

• Keep this implementation on repo artifacts only: inventory, risk or disposition matrix, standards delta, and follow-up map.
• Use the named runtime anchors as inventory sources only. Do not patch those anchors inside this audit slice.
• When a cue cannot prove a truthful denominator, direction, freshness, or scope, classify it as ambiguous or risky and route it to one bounded follow-up lane instead of forcing a local semantic answer.
• Keep later follow-up work split into separate candidates or specs:
  • standards patch lane
  • metric/indicator contract foundation
  • shared indicator component system
  • quality gate lane
  • domain migration lane
• Do not reopen Specs 266, 268, 270, 271, or 272 inside this package.

Research & Design Outputs

• research.md records the repo-based scope decision, output artifact shape, vocabulary decision, standards-delta target, follow-up-lane split, and docs-only validation posture.
• data-model.md captures the docs-only inventory, standards-delta, and follow-up-map entities and their required fields.
• quickstart.md provides the bounded reviewer flow and the canonical docs-only validation commands.
• contracts/cross-domain-indicator-audit.logical.openapi.yaml captures the conceptual repository-artifact contract for the inventory, standards delta, and follow-up map.
• checklists/requirements.md carries the prep review outcome, workflow outcome, and test-governance outcome.
• inventory.md contains the completed repo-based cue inventory and one-category/one-disposition classification.
• follow-up-map.md groups non-keep recommendations into the five bounded later lanes.
• standards-delta.md records the distilled standards rules applied to the UI standards document.

Project Structure

Documentation (this feature)

specs/278-cross-domain-indicator-audit/
├── checklists/
│   └── requirements.md
├── contracts/
│   └── cross-domain-indicator-audit.logical.openapi.yaml
├── data-model.md
├── follow-up-map.md
├── inventory.md
├── plan.md
├── quickstart.md
├── research.md
├── spec.md
├── standards-delta.md
└── tasks.md

Repo reference surfaces audited as evidence

docs/product/spec-candidates.md
docs/product/roadmap.md
docs/ui/tenantpilot-enterprise-ui-standards.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
apps/platform/app/Support/TenantDashboard/TenantDashboardSummaryBuilder.php

Structure Decision: keep the prep package and its later docs implementation inside spec artifacts plus explicit documentation targets. Runtime presenters, widgets, and services are source anchors only and remain untouched in this slice.

Complexity Tracking

Violation	Why Needed	Simpler Alternative Rejected Because
Documentation-only taxonomy and audit bundle	The repo has multiple visually similar cues but no product-wide semantics inventory or bounded follow-up map	A cue-by-cue local cleanup would miss cross-domain drift and would still force later specs to repeat discovery

Proportionality Review

• Current operator problem: reviewers and operators can misread similar progress-like cues as equivalent even when they represent different product truth.
• Existing structure is insufficient because: current presenters, widgets, services, and standards describe local meaning only and do not inventory or classify cross-domain semantics.
• Narrowest correct implementation: one docs-only audit bundle, one standards-delta input, and one explicit follow-up map grounded in current repo surfaces.
• Ownership cost created: maintenance of the vocabulary, audit matrix, and follow-up discipline in future specs and reviews.
• Alternative intentionally rejected: immediate runtime contract, shared component, quality-gate implementation, or domain migration work was rejected because it would widen scope before the audit exists.
• Release truth: current-release docs and governance groundwork with explicit future follow-up specs for runtime work.