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

Research — Cross-Domain Progress Indicator Semantics Audit

Date: 2026-05-06
Branch: 278-cross-domain-indicator-audit

Decision 1 — Keep the slice repo-based and docs/governance-first

• Decision: Treat this package as a repository-governance audit only. The later implementation of this slice should create or update inventory, standards-delta, and follow-up artifacts without changing application code, tests, routes, assets, or panel wiring.
• Rationale: The spec frames the current gap as semantic drift and missing inventory, not a missing runtime component. The smallest safe correction is therefore a repo-based audit bundle.
• Alternatives considered: Starting with shared indicator components, contract code, dashboard rewrites, or score cleanup was rejected because each option widens scope before the product has one explicit inventory of what current cues actually mean.

Decision 2 — Keep the implementation outputs in the feature package first and target the UI standard as derived delta

• Decision: Keep the main audit outputs inside specs/278-cross-domain-indicator-audit/ and treat docs/ui/tenantpilot-enterprise-ui-standards.md as the future standards-delta destination rather than the first place where the full inventory lives.
• Rationale: The feature package is the narrowest place to hold the full audit bundle, risk matrix, and follow-up map. The UI standard should receive the distilled rule delta later, not absorb the whole research inventory.
• Alternatives considered: Writing the full inventory straight into docs/ui/tenantpilot-enterprise-ui-standards.md was rejected because it would mix durable standards with audit evidence and make follow-up review harder.

Decision 3 — Inventory named anchors plus bounded repo search, not isolated local surfaces

• Decision: Use the named source anchors from the spec and a bounded repo search for additional indicator-like cues in the same scope. Treat anchors such as OperationUxPresenter, InventoryKpiHeader, RecoveryReadiness, BaselineSnapshotPresenter, ReviewPackService, and TenantDashboardSummaryBuilder as source surfaces only.
• Rationale: The spec already names representative seams, but it also requires repo-based discovery beyond those anchors. A mixed anchor-plus-search approach keeps the audit grounded while still finding additional cues that share the same drift risk.
• Alternatives considered: Auditing only the named files was rejected because it could miss nearby Blade or widget seams. Searching the entire repo without anchor guidance was rejected because it would widen discovery beyond the bounded slice.

Decision 4 — Keep one documentation-only category vocabulary and assign exactly one category per cue

• Decision: Reuse the spec's category set as the only allowed semantics vocabulary in this slice: execution progress, activity state, coverage, completion, health, readiness, risk, pressure, usage, capacity, score, generation state, and unknown/ambiguous.
• Rationale: The spec already defines the bounded vocabulary and requires exactly one category per cue. Reusing that set keeps the package consistent and prevents a second ad hoc taxonomy from appearing during planning.
• Alternatives considered: Adding secondary category tags, subcategories, or a new risk-severity enum was rejected because the current-release need is classification clarity, not another semantic framework.

Decision 5 — Capture scope, audience, determinism, and data-basis metadata alongside meaning

• Decision: Every inventory entry should carry scope mode, audience mode, determinism, visible pattern, and data-basis notes in addition to the semantic category and disposition.
• Rationale: The same visual cue can be misleading for different reasons: fake progress, stale data, hidden tenant scope, or customer-safe wording drift. Category alone is not enough to explain why a cue is safe or risky.
• Alternatives considered: A slimmer inventory with only label, category, and recommendation was rejected because it would not preserve the tenant, audience, and determinism context the spec explicitly calls out.

Decision 6 — Treat provider-owned cues as examples inside a neutral platform vocabulary

• Decision: Record provider-health and permission-posture cues as provider-owned examples while keeping the audit's category language platform-neutral.
• Rationale: The constitution and spec both require shared platform vocabulary to avoid becoming Microsoft-shaped truth. The audit needs to show that some examples remain provider-specific without letting those examples define the whole taxonomy.
• Alternatives considered: Generalizing provider-specific examples into platform-core semantics was rejected because it would deepen provider coupling. Excluding them entirely was rejected because they are real current cues and part of the product's ambiguity problem.

Decision 7 — Split later work into five explicit follow-up lanes

• Decision: Keep later work separated into the standards patch lane, metric/indicator contract foundation, shared indicator component system, quality gate lane, and domain migration lane.
• Rationale: The spec explicitly forbids one giant cleanup program. Separate lanes keep later implementation reviewable and stop this audit from being read as permission for an immediate runtime rewrite.
• Alternatives considered: One generic "indicator cleanup" follow-up was rejected because it hides architecture, migration, and governance costs behind a single vague bucket.

Decision 8 — Reuse the current prep convention for checklist and validation handling

• Decision: Create a package-local checklist artifact and keep one canonical docs-only validation command set across spec.md, plan.md, quickstart.md, and the checklist.
• Rationale: Nearby Specs 275 and 277 both carry explicit review outcome, workflow outcome, and test-governance outcome handling in addition to the plan. This slice needs the same prep discipline even though the proving lane is docs-only.
• Alternatives considered: Relying only on prose review notes in plan.md was rejected because the repo's current prep convention expects a dedicated checklist artifact and explicit outcome language.

Decision 9 — Use docs-only validation rather than runtime tests

• Decision: Validate this package with focused diff and grep commands plus reviewer checklist verification, not runtime tests or browser smoke.
• Rationale: This slice changes only preparation artifacts. Running Sail, Pint, or app tests would not prove anything about the correctness of the audit package itself.
• Alternatives considered: Adding runtime tests or browser checks was rejected because they would imply application behavior changed, which is explicitly out of scope.

Decision 10 — Lock the implementation outputs and lane handoff

• Decision: Treat inventory.md, follow-up-map.md, and standards-delta.md as the completed package-local implementation outputs. The target UI standards document receives a concise indicator-semantics delta, while docs/product/spec-candidates.md and docs/product/roadmap.md receive only follow-up-lane references.
• Rationale: The inventory needs enough detail for future specs, but product standards and backlog documents should not absorb the whole audit table. Separating the detailed audit from distilled standards and roadmap handoff keeps the current slice reviewable and prevents runtime cleanup from hiding inside documentation work.
• Alternatives considered: Copying the full inventory into the standards document, creating new spec candidates as separate files, or updating application source comments were rejected because each would widen the docs-only audit beyond the bounded package.