TenantAtlas/specs/278-cross-domain-indicator-audit/data-model.md

Data Model: Cross-Domain Progress Indicator Semantics Audit

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

Overview

This slice introduces no runtime persistence, no new application DTO layer, and no new state family. The package defines documentation-only audit artifacts over existing repo-real cues so later specs can build on one explicit inventory and standards delta.

Reused Source Truth

1. Indicator Source Anchor

Persistence: none, repo source reference only
Owner: current documentation and code seams already present in the monorepo

Field	Type	Required	Notes
repo_path	string	yes	Absolute or repo-relative file path to the source seam
source_type	string	yes	standard, spec, presenter, widget, service, builder, blade, or other-code
surface_name	string	yes	Human-readable surface or seam name
domain	string	yes	Ops, inventory, backup, review, baseline, provider posture, tenant summary, or similar
route_context	string	no	Known current route or shell context when relevant
notes	string	no	Why this anchor matters to the audit

Behavior rules:

• Source anchors are audit evidence only in this slice.
• Adding an anchor to the audit does not imply that the file will be changed.
• The audit must capture enough anchors to explain the current cross-domain drift without widening into unrelated domains.

2. Related Spec Guardrail

Persistence: none, repo context only
Owner: current spec package

Field	Type	Required	Notes
spec_id	string	yes	Existing adjacent spec number
relation	string	yes	context-only, guardrail, or follow-up dependency
note	string	yes	What the audit must preserve or avoid reopening
out_of_scope_for_this_slice	boolean	yes	Always true for this package

Required rows:

• 266
• 268
• 270
• 271
• 272

Derived Audit Artifacts

3. Indicator Inventory Entry

Persistence: none, documentation artifact only
Owner: audit inventory bundle

Field	Type	Required	Notes
entry_id	string	yes	Stable audit-local identifier
source_anchor_ref	string	yes	Link to the source anchor entry
surface	string	yes	The visible surface or seam where the cue appears
domain	string	yes	Product domain owning the cue
visible_cue	string	yes	Label, wording, or short description of the cue
visual_pattern	string	yes	Badge, percentage, bar, KPI stat, helper text, summary row, empty-state signal, or similar
data_source	string	yes	Current repo-real truth feeding the cue
calculation_basis	string	yes	How the cue is currently derived, or not explicit when unclear
semantic_category	string	yes	Exactly one allowed category from the list below
determinism	string	yes	determinate, indeterminate, or unknown
scope_mode	string	yes	tenant-prefiltered, tenantless-aggregate, workspace-aggregate, or supporting-context
audience_mode	string	no	customer-readable, operator-msp, support-platform, mixed, or not-applicable
likely_user_reading	string	yes	What an operator or reviewer is likely to infer from the cue
misunderstanding_risk	string	yes	Risk note describing why the cue may mislead
disposition	string	yes	Exactly one bounded recommendation from the disposition set below
follow_up_lane	string	no	Required for every disposition except keep as-is; values come from the follow-up map lane set
related_guardrails	array	no	Adjacent specs or standards rules that constrain follow-up work
notes	string	no	Extra explanation or uncertainty

Validation rules:

• One cue gets exactly one inventory entry unless the surface shows multiple visibly separate cues.
• One inventory entry gets exactly one semantic category.
• One inventory entry gets exactly one disposition.
• follow_up_lane is required when disposition is anything other than keep as-is.
• unknown/ambiguous is the fallback category when the current repo truth cannot support a more precise category safely.

4. Semantic Category

Persistence: none, documentation-only enum
Owner: audit vocabulary

Allowed values:

• execution progress
• activity state
• coverage
• completion
• health
• readiness
• risk
• pressure
• usage
• capacity
• score
• generation state
• unknown/ambiguous

Behavior rules:

• Categories are documentation-only in this slice and do not create new runtime state.
• Categories must remain mutually exclusive at the cue level.
• A visually similar pattern on two surfaces may map to different categories when the underlying truth differs.

5. Recommendation Disposition

Persistence: none, documentation-only enum
Owner: audit recommendation layer

Allowed values:

• keep as-is
• copy-only clarification
• standards clarification
• product decision
• contract follow-up
• shared-component follow-up
• migration follow-up
• defer

Behavior rules:

• Dispositions describe the next bounded action, not the full implementation plan.
• keep as-is is allowed only when the cue is already semantically honest.
• copy-only clarification and standards clarification should normally route to the standards patch lane.
• contract follow-up, shared-component follow-up, and migration follow-up must map to their matching follow-up lanes.

6. Standards Delta Rule

Persistence: none, documentation artifact only
Owner: standards-delta bundle

Field	Type	Required	Notes
rule_id	string	yes	Stable rule identifier inside the audit package
area	string	yes	allowed-categories, determinate-progress, freshness, wording, dashboard, anti-pattern, or provider-boundary
current_gap	string	yes	What the current repo does not state clearly enough
proposed_guidance	string	yes	Intended standards delta wording
target_doc	string	yes	Expected future standards target, normally docs/ui/tenantpilot-enterprise-ui-standards.md
follow_up_lane	string	no	Usually standards patch lane, but may point elsewhere when the gap cannot be solved by documentation alone

7. Follow-Up Map Entry

Persistence: none, documentation artifact only
Owner: follow-up map bundle

Field	Type	Required	Notes
lane	string	yes	One of the bounded lane names below
purpose	string	yes	What this lane exists to solve
out_of_scope_for_this_slice	boolean	yes	Always true in this package
trigger_cues	array	yes	Inventory entries or cue families that justify the lane
likely_repo_surfaces	array	yes	Docs or code anchors the later spec will probably need
seed_questions	array	no	Questions the later spec must answer before implementation

Required lane values:

• standards patch lane
• metric/indicator contract foundation
• shared indicator component system
• quality gate lane
• domain migration lane

8. Audit Bundle

Persistence: none, documentation artifact only
Owner: current spec package

Field	Type	Required	Notes
inventory	array	yes	List of Indicator Inventory Entry objects
standards_delta	array	yes	List of Standards Delta Rule objects
follow_up_map	array	yes	List of Follow-Up Map Entry objects
related_spec_guardrails	array	yes	Context-only guardrails from existing adjacent specs
review_outcome_class	string	yes	Current prep convention outcome class
workflow_outcome	string	yes	Current prep convention workflow outcome
test_governance_outcome	string	yes	Current prep convention test-governance outcome

Derived Rules

Rule	Derived Behavior
One cue, one meaning	Every visible cue must map to exactly one semantic category
One cue, one next action	Every visible cue must map to exactly one disposition
Scope is first-class	Every cue must record whether it looks tenant-prefiltered, tenantless aggregate, workspace aggregate, or only supporting context
Ambiguity is explicit	Unknown denominator, freshness, or scope becomes risk documentation, not a guessed category
Follow-up work stays separate	Contract, component, quality-gate, and migration work remain distinct later lanes
Audit outputs stay docs-only	No runtime table, code path, or presenter becomes part of this slice

Boundaries Explicitly Preserved

• No new runtime source of truth is introduced.
• No shared runtime contract, component, migration, chart, or score engine is introduced.
• No existing presenter, widget, service, or Blade surface is rewritten in this slice.
• Product backlog docs may be referenced by the follow-up map, but the audit bundle itself remains the primary output.