version: 1
feature: 223-astrodeck-website-rebuild
description: File-based contract for the planning artifacts required by the AstroDeck rebuild workflow.

artifacts:
  astroDeckSourceIntake:
    description: Reviewable source-intake record for the AstroDeck snapshot being evaluated before primitive mapping begins.
    type: object
    required:
      - sourceSnapshotReference
      - intakeConstraints
      - reviewAssumptions
    properties:
      sourceSnapshotReference:
        type: string
      intakeConstraints:
        type: array
        items:
          type: string
      reviewAssumptions:
        type: array
        items:
          type: string

  currentWebsiteInventory:
    description: Current `apps/website` surface inventory captured before any AstroDeck replacement work starts.
    type: object
    required:
      - surfaces
    properties:
      surfaces:
        type: array
        items:
          type: object
          required:
            - route
            - sourceFile
            - surfaceRole
            - governingSpecs
            - plannedDisposition
          properties:
            route:
              type: string
            sourceFile:
              type: string
            surfaceRole:
              type: string
            governingSpecs:
              type: array
              items:
                type: integer
            currentDependencies:
              type: array
              items:
                type: string
            plannedDisposition:
              type: string
              enum: [keep, adapt, remove, redirect]

  astroDeckPrimitiveInventory:
    description: Inventory of candidate AstroDeck pages, sections, and components.
    type: object
    required:
      - primitives
    properties:
      primitives:
        type: array
        items:
          type: object
          required:
            - primitiveId
            - primitiveType
            - sourceReference
          properties:
            primitiveId:
              type: string
            primitiveType:
              type: string
              enum: [page, section, component]
            sourceReference:
              type: string
            candidateSurfaces:
              type: array
              items:
                type: string
            demoContentFlags:
              type: array
              items:
                type: string
            notes:
              type: string

  governingSpecClassification:
    description: Classification of the active website spec set before rebuild implementation starts.
    type: object
    required:
      - specs
    properties:
      specs:
        type: array
        items:
          type: object
          required:
            - specId
            - title
            - classification
            - scopeSummary
            - rationale
            - followUpPlan
          properties:
            specId:
              type: integer
            title:
              type: string
            classification:
              type: string
              enum: [continuing, "partially valid", superseded]
            scopeSummary:
              type: string
            rationale:
              type: string
            followUpPlan:
              description: Path to the per-spec mapping artifact or explicit supersession-closure artifact that owns current-slice delivery for this spec.
              type: string

  primitiveMapping:
    description: Mapping of one governing website spec requirement to one AstroDeck primitive, including the replacement task ownership embedded in the same per-spec artifact.
    type: object
    required:
      - mappings
    properties:
      mappings:
        type: array
        items:
          type: object
          required:
            - specId
            - requirementReference
            - disposition
            - acceptanceMapping
            - replacementTasks
          properties:
            specId:
              type: integer
            requirementReference:
              type: string
            primitiveId:
              description: Required when disposition is keep, adapt, or remove; omitted when disposition is exception.
              type: string
            disposition:
              type: string
              enum: [keep, adapt, remove, exception]
            adaptationSummary:
              type: string
            acceptanceMapping:
              type: string
            replacementTasks:
              description: Ordered replacement task list owned by the same per-spec mapping or disposition artifact.
              type: array
              items:
                type: string
            taskPrimitiveReferences:
              description: Named AstroDeck pages, sections, components, or explicit mapping activities referenced by the replacement task list.
              type: array
              items:
                type: string
            materialDriftReferences:
              type: array
              items:
                type: string
            exceptionReference:
              type: string
          oneOf:
            - properties:
                disposition:
                  enum: [keep, adapt, remove]
              required:
                - primitiveId
            - properties:
                disposition:
                  enum: [exception]
              required:
                - exceptionReference

  supersessionClosure:
    description: Explicit closure artifact for an in-scope website spec that ends the rebuild review as superseded instead of continuing into a mapping-based plan.
    type: object
    required:
      - specId
      - classification
      - closureRationale
      - legacyTaskDispositionReference
      - replacementReference
    properties:
      specId:
        type: integer
      classification:
        type: string
        enum: [superseded]
      closureRationale:
        type: string
      legacyTaskDispositionReference:
        type: string
      replacementReference:
        description: Replacement plan reference or an explicit `no replacement work required` statement.
        type: string
      notes:
        type: string

  legacyTaskDisposition:
    description: Historical task record preserved while being superseded by the rebuild.
    type: object
    required:
      - dispositions
    properties:
      dispositions:
        type: array
        items:
          type: object
          required:
            - originalSpecId
            - originalTaskReference
            - disposition
            - replacementReference
          properties:
            originalSpecId:
              type: integer
            originalTaskReference:
              type: string
            disposition:
              type: string
              enum: ["superseded by AstroDeck rebuild"]
            replacementReference:
              description: New plan, task set, or an explicit `no replacement work required` statement.
              type: string
            notes:
              type: string

  materialDriftFollowUp:
    description: Explicit spec-update follow-up record for material page inventory, CTA logic, navigation, or trust messaging drift discovered during mapping.
    type: object
    required:
      - driftRecords
    properties:
      driftRecords:
        type: array
        items:
          type: object
          required:
            - affectedSpecId
            - driftClass
            - driftSummary
            - requiredSpecAction
            - targetSpecReference
          properties:
            affectedSpecId:
              type: integer
            driftClass:
              type: string
              enum: ["page inventory", "CTA logic", navigation, "trust messaging"]
            driftSummary:
              type: string
            requiredSpecAction:
              type: string
              enum: ["update existing spec", "create follow-up spec"]
            targetSpecReference:
              type: string
            notes:
              type: string

  exceptionRegister:
    description: Standing review register for missing-candidate checks, including approved exceptions and explicit no-exception outcomes.
    type: object
    required:
      - entries
    properties:
      entries:
        type: array
        items:
          type: object
          required:
            - specId
            - scope
            - reviewOutcome
            - reviewRationale
          properties:
            specId:
              type: integer
            scope:
              type: string
            reviewOutcome:
              type: string
              enum: ["approved exception", "no exception required"]
            reviewRationale:
              type: string
            exceptionReference:
              type: string
            notes:
              type: string
          oneOf:
            - properties:
                reviewOutcome:
                  enum: ["approved exception"]
              required:
                - exceptionReference
            - properties:
                reviewOutcome:
                  enum: ["no exception required"]

  documentedException:
    description: Approved exception record for custom work when no adequate AstroDeck primitive exists, stored inside the exception register when reviewOutcome is `approved exception`.
    type: object
    required:
      - exceptions
    properties:
      exceptions:
        type: array
        items:
          type: object
          required:
            - scope
            - missingCandidate
            - unmetRequirement
            - adequacyFailureReason
            - boundedDeviation
            - approvedBy
            - approvalReference
            - spreadControl
          properties:
            scope:
              type: string
            missingCandidate:
              type: string
            unmetRequirement:
              type: string
            adequacyFailureReason:
              type: string
            boundedDeviation:
              type: string
            approvedBy:
              type: string
            approvalReference:
              type: string
            spreadControl:
              type: string