TenantAtlas/specs/223-astrodeck-website-rebuild/data-model.md

# Data Model: Website Reset and AstroDeck Rebuild

This feature does not introduce runtime persistence. The entities below define the planning artifacts that must exist for the rebuild workflow to remain reviewable and deterministic.

## Entity: LegacyWebsiteImplementation

- **Purpose**: Represents the current `apps/website` codebase as the retired implementation substrate.
- **Fields**:
  - `scopePath`: repository path being retired, currently `apps/website`
  - `status`: discarded implementation history
  - `replacedBySpec`: spec reference that formally retires it, `223-astrodeck-website-rebuild`
  - `notes`: short rationale for why it is no longer the active base
- **Relationships**:
  - One `LegacyWebsiteImplementation` has many `LegacyTaskDisposition` records.

## Entity: CurrentWebsiteSurface

- **Purpose**: Captures the existing public routes and current website surfaces that must be reconciled during rebuild planning.
- **Fields**:
  - `route`: public route, such as `/`, `/product`, `/trust`, `/contact`, `/legal`
  - `sourceFile`: current Astro page file
  - `surfaceRole`: current role in the website IA, such as core, secondary, legal, redirect, or optional
  - `governingSpecs`: list of active website specs that currently constrain the surface
  - `currentDependencies`: content collections, layout primitives, tests, or redirects tied to the surface
  - `plannedDisposition`: keep, adapt, remove, or redirect
- **Relationships**:
  - A `CurrentWebsiteSurface` may map to one or more `AstroDeckPrimitive` candidates through `PrimitiveMapping`.

## Entity: AstroDeckSourceIntake

- **Purpose**: Captures the reviewable AstroDeck source snapshot, intake constraints, and working assumptions before primitive mapping begins.
- **Fields**:
  - `sourceSnapshotReference`: path, tag, archive name, or other stable reference for the imported AstroDeck source
  - `intakeConstraints`: list of intake limitations, licensing boundaries, or review constraints
  - `reviewAssumptions`: explicit assumptions used while building the primitive inventory and mappings
  - `notes`: traceability details for reviewers
- **Relationships**:
  - One `AstroDeckSourceIntake` may inform many `AstroDeckPrimitive` records.

## Entity: GoverningWebsiteSpec

- **Purpose**: Tracks each existing website spec that must be classified before rebuild work continues.
- **Fields**:
  - `specId`: current spec number, initially one of 213, 214, 215, 217, 218
  - `title`: short spec title
  - `classification`: continuing, partially valid, or superseded
  - `scopeSummary`: what part of the website the spec governs
  - `followUpPlan`: reference to the per-spec mapping artifact or explicit supersession-closure artifact that owns current-slice delivery for this spec
  - `rationale`: why the classification was chosen
- **Relationships**:
  - One `GoverningWebsiteSpec` has many `PrimitiveMapping` records.
  - One `GoverningWebsiteSpec` has many `LegacyTaskDisposition` records.
  - One `GoverningWebsiteSpec` may have one `SupersessionClosure` when rebuild planning ends with an explicit closure instead of a mapping plan.

## Entity: SupersessionClosure

- **Purpose**: Captures the explicit closure artifact used when an in-scope website spec is classified as superseded and therefore does not continue into a mapping-based rebuild plan.
- **Fields**:
  - `specId`: governing website spec being closed out
  - `classification`: superseded
  - `closureRationale`: why the spec no longer needs a rebuild mapping artifact
  - `legacyTaskDispositionReference`: where the superseded legacy tasks were recorded
  - `replacementReference`: replacement plan reference or explicit `no replacement work required` statement
  - `notes`: traceability details for reviewers
- **Relationships**:
  - One `SupersessionClosure` belongs to one `GoverningWebsiteSpec`.

## Entity: AstroDeckPrimitive

- **Purpose**: Represents a candidate AstroDeck page, section, or component available for rebuild mapping.
- **Fields**:
  - `primitiveId`: stable identifier inside the imported AstroDeck inventory
  - `primitiveType`: page, section, or component
  - `sourceReference`: where the primitive came from inside the AstroDeck source snapshot
  - `candidateSurfaces`: current routes or spec requirements it may satisfy
  - `demoContentFlags`: whether it carries demo copy, demo media, or demo CTA behavior that may require removal
  - `notes`: freeform adaptation concerns
- **Relationships**:
  - One `AstroDeckPrimitive` may be referenced by many `PrimitiveMapping` records.

## Entity: PrimitiveMapping

- **Purpose**: Records how a governing website spec requirement maps to one AstroDeck primitive or falls through to a documented missing-candidate exception path, including the replacement task ownership captured inside the same per-spec artifact.
- **Fields**:
  - `specId`: owning website spec
  - `requirementReference`: spec requirement, acceptance point, or surface requirement being mapped
  - `primitiveId`: referenced AstroDeck primitive when a concrete candidate exists; omitted when the disposition is `exception`
  - `disposition`: keep, adapt, remove, or exception
  - `adaptationSummary`: required changes to route, structure, styling, copy slots, or CTA behavior
  - `acceptanceMapping`: how the mapped primitive satisfies the spec once adapted
  - `replacementTasks`: ordered replacement task list owned by the same per-spec mapping or disposition artifact
  - `taskPrimitiveReferences`: named AstroDeck pages, sections, components, or explicit mapping activities referenced by the replacement task list
  - `materialDriftReferences`: references to updated or follow-up website specs required when AstroDeck adoption changes page inventory, CTA logic, navigation, or trust messaging
  - `exceptionReference`: linked `DocumentedException` record when the disposition is `exception`
- **Relationships**:
  - Many `PrimitiveMapping` records belong to one `GoverningWebsiteSpec`.
  - Many `PrimitiveMapping` records may target one `AstroDeckPrimitive`.
  - One `PrimitiveMapping` may have zero or one `DocumentedException`.

## Entity: ExceptionRegisterEntry

- **Purpose**: Captures the review outcome for each missing-candidate check so the rebuild keeps a standing register of approved exceptions and explicit no-exception outcomes.
- **Fields**:
  - `specId`: governing website spec under review
  - `scope`: page, section, component, or route slice being checked
  - `reviewOutcome`: approved exception or no exception required
  - `reviewRationale`: why the review produced that outcome
  - `exceptionReference`: linked `DocumentedException` when the outcome is approved exception
  - `notes`: traceability details for reviewers
- **Relationships**:
  - Many `ExceptionRegisterEntry` records belong to one `GoverningWebsiteSpec`.
  - One `ExceptionRegisterEntry` may reference zero or one `DocumentedException`.

## Entity: MaterialDriftFollowUp

- **Purpose**: Captures any material page inventory, CTA logic, navigation, or trust messaging change discovered during mapping so it becomes an explicit spec update instead of silent template drift.
- **Fields**:
  - `affectedSpecId`: governing website spec whose truth must be updated or followed up
  - `driftClass`: page inventory, CTA logic, navigation, or trust messaging
  - `driftSummary`: concise description of what changed materially
  - `requiredSpecAction`: update existing spec or create follow-up spec
  - `targetSpecReference`: path to the existing spec or named follow-up spec that owns the change
  - `notes`: rationale and traceability details
- **Relationships**:
  - Many `MaterialDriftFollowUp` records may belong to one `GoverningWebsiteSpec`.

## Entity: LegacyTaskDisposition

- **Purpose**: Preserves old website implementation task history while marking it as no longer authoritative.
- **Fields**:
  - `originalSpecId`: spec that owned the original task
  - `originalTaskReference`: stable task identifier or short description
  - `disposition`: `superseded by AstroDeck rebuild`
  - `replacementReference`: new plan, spec, or task set that replaces the old task
  - `notes`: why the original task cannot simply be reopened
- **Relationships**:
  - Many `LegacyTaskDisposition` records belong to one `LegacyWebsiteImplementation`.
  - Many `LegacyTaskDisposition` records may be associated with one `GoverningWebsiteSpec`.

## Entity: DocumentedException

- **Purpose**: Captures the narrow approved cases where no adequate AstroDeck primitive exists and custom work is justified, stored as the approved-exception detail inside the exception register.
- **Fields**:
  - `scope`: page, section, component, or route slice that needs an exception
  - `missingCandidate`: statement of which AstroDeck search failed
  - `unmetRequirement`: the active website-spec requirement that could not be satisfied
  - `adequacyFailureReason`: why keep or bounded adaptation could not satisfy the requirement
  - `boundedDeviation`: precise custom work being allowed
  - `approvedBy`: named website reviewer, owner, or equivalent feature approver
  - `approvalReference`: spec, review note, or task entry that owns the exception
  - `spreadControl`: explicit statement of why the exception stays local
- **Relationships**:
  - One `DocumentedException` belongs to one `PrimitiveMapping`.
  - One `DocumentedException` is represented by one approved `ExceptionRegisterEntry`.

## Validation Rules

- Every continuing or partially valid `GoverningWebsiteSpec` must have at least one `PrimitiveMapping` before implementation starts.
- Every `CurrentWebsiteSurface` must end the planning phase with an explicit disposition.
- Every `LegacyTaskDisposition` must point to a replacement reference or explicitly state that no replacement work is required.
- Every `DocumentedException` must name the failed AstroDeck candidate search, the unmet requirement, the adequacy failure reason, the bounded deviation, and the named approver.
- Every material page inventory, CTA logic, navigation, or trust messaging change discovered during mapping must create a `MaterialDriftFollowUp` record that points to an updated or follow-up website spec.
- Every missing-candidate review must create an `ExceptionRegisterEntry` with outcome `approved exception` or `no exception required`.
- Every replacement task list must name the relevant AstroDeck page, section, component, or mapping activity instead of using generic build wording.
- No `PrimitiveMapping` may use `exception` as its disposition without a linked `ExceptionRegisterEntry` and `DocumentedException`.

## State Transitions

- `GoverningWebsiteSpec.classification`: `unreviewed -> continuing | partially valid | superseded`
- `CurrentWebsiteSurface.plannedDisposition`: `discovered -> keep | adapt | remove | redirect`
- `PrimitiveMapping.disposition`: `candidate -> keep | adapt | remove | exception`
- `ExceptionRegisterEntry.reviewOutcome`: `reviewed -> approved exception | no exception required`
- `DocumentedException`: `gap identified -> approved exception record`
- `LegacyTaskDisposition.disposition`: `historical -> superseded by AstroDeck rebuild`

## Notes

- These entities are planning artifacts only. They do not imply new database tables, application models, or runtime services.