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.