TenantAtlas/specs/223-astrodeck-website-rebuild/spec.md

Feature Specification: Website Reset and AstroDeck Rebuild

Feature Branch: 223-astrodeck-website-rebuild
Created: 2026-04-22
Status: Approved
Input: User description: "Reset and rebuild apps/website on AstroDeck with strict AstroDeck primitive mapping, preserved website spec truth, superseded legacy implementation tasks, and documented exceptions for any non-AstroDeck rebuild work."

Spec Candidate Check (mandatory — SPEC-GATE-001)

• Problem: apps/website has an existing implementation and task history that no longer match the desired implementation substrate, so future work can drift between legacy code, template import, and undocumented greenfield rebuilding.
• Today's failure: Contributors could delete the old website, import AstroDeck, and reopen legacy tasks as if nothing materially changed, which would erase the strategy shift and make planning history misleading.
• User-visible improvement: Website contributors and reviewers can rebuild on a clearly defined base, preserve existing public-surface spec truth, and distinguish legacy work from the new forward plan without guesswork.
• Smallest enterprise-capable version: One apps/website-local reset-and-rebuild governance spec that declares the prior implementation superseded, makes AstroDeck the required substrate, classifies existing website specs, preserves legacy task history, and requires fresh AstroDeck-specific replanning.
• Explicit non-goals: No final page visuals, no final copy, no file-by-file migration guide, no platform or Filament changes, no automatic reapproval of every website spec, and no unrestricted greenfield redesign.
• Permanent complexity imported: A website-local rebuild contract, AstroDeck primitive inventory and mapping vocabulary, a superseded-task policy, and a narrow exception workflow for cases where the chosen base primitives are insufficient.
• Why now: More website work is already blocked by uncertainty about whether the old implementation still matters and whether new work should inherit template defaults or existing website specs.
• Why not local: A one-off migration note or template import would not preserve task history, would not classify which website specs still govern the site, and would not force future work onto one visible substrate.
• Approval class: Cleanup
• Red flags triggered: #1 introduces a new planning classification layer; #4 uses foundation/substrate language; #6 naturally leads to follow-up planning specs. The scope remains justified because it replaces ambiguity with one local contract and prevents silent drift during a full implementation reset.
• Score: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitaet: 2 | Produktnaehe: 1 | Wiederverwendung: 2 | Gesamt: 11/12
• Decision: approve

Spec Scope Fields (mandatory)

• Scope: workspace
• Primary Routes: All public routes in apps/website, starting with the current website route family governed by Specs 213, 214, 215, 217, and 218, including /, /product, /trust, /changelog, /contact, /privacy, and /imprint.
• Data Ownership: Website-owned planning truth only: implementation-basis selection, AstroDeck primitive inventory and mapping, continuing-spec classification, superseded legacy task treatment, and documented exception records. No tenant-owned records, platform runtime data, or shared persistence are introduced.
• RBAC: None. This feature governs repository planning and public-website implementation rules only.

UI / Surface Guardrail Impact (mandatory when operator-facing surfaces are changed; otherwise write N/A)

N/A - no operator-facing surface change. This feature governs website implementation basis, planning artifacts, and legacy task treatment inside apps/website.

Proportionality Review (mandatory when structural complexity is introduced)

• New source of truth?: yes
• New persisted entity/table/artifact?: no
• New abstraction?: yes
• New enum/state/reason family?: no
• New cross-domain UI framework/taxonomy?: yes, but only within apps/website planning and implementation governance
• Current operator problem: Website contributors and reviewers cannot currently tell which website specs survive the reset, which tasks are obsolete, and whether new work must start from AstroDeck or from custom rebuilding.
• Existing structure is insufficient because: The current website specs describe public-surface truth, but they do not define how a full implementation reset should preserve that truth, retire legacy tasks, or make AstroDeck mandatory for forward work.
• Narrowest correct implementation: One website-local reset spec that fixes the implementation basis, legacy-task treatment, replanning workflow, and bounded exception policy without redefining page design or expanding into platform governance.
• Ownership cost: Future website planning must keep continuing specs classified, legacy tasks visibly superseded, AstroDeck mappings explicit, and exceptions tightly bounded instead of allowing ad hoc drift.
• Alternative intentionally rejected: Deleting the old website, importing AstroDeck, and reopening old tasks was rejected because it would erase the strategy shift, hide replanning work, and make implementation history unreliable.
• Release truth: Current-release truth for the public website only; this is not a platform-wide workflow contract.

Compatibility posture

This feature assumes a pre-production environment.

Backward compatibility for the discarded website implementation, migration shims for legacy pages, and preservation of obsolete implementation structure are out of scope unless a later spec explicitly requires them.

Canonical replacement through the new substrate is preferred over preservation.

Testing / Lane / Runtime Impact (mandatory for runtime behavior changes)

• Test purpose / classification: N/A
• Validation lane(s): N/A
• Why this classification and these lanes are sufficient: This feature changes specification and planning truth only. It does not by itself change runtime behavior, browser surfaces, or automated test obligations.
• New or expanded test families: none
• Fixture / helper cost impact: none
• Heavy-family visibility / justification: none
• Special surface test profile: N/A
• Standard-native relief or required special coverage: none; follow-up implementation specs must define their own build and browser proof.
• Reviewer handoff: Reviewers must confirm that the spec clearly separates discarded implementation from continuing spec truth, preserves task history, makes the implementation substrate explicit, and bounds exceptions instead of allowing greenfield bypass.
• Budget / baseline / trend impact: none
• Escalation needed: none
• Active feature PR close-out entry: N/A
• Planned validation commands: N/A - specification quality review only

User Scenarios & Testing (mandatory)

User Story 1 - Start rebuild work from one visible substrate (Priority: P1)

A website contributor begins a new apps/website implementation slice and can tell immediately that the old website implementation no longer governs forward work and that the rebuild must start from AstroDeck primitives.

Why this priority: If the implementation basis remains ambiguous, every follow-up website task risks mixing discarded code, template defaults, and unreviewed custom work.

Independent Test: Review the reset spec and one follow-up planning artifact and confirm that the implementation starts from identified base pages, sections, and components rather than from the discarded website or a generic "build" task.

Acceptance Scenarios:

1. Given the previous website implementation still exists in repository history, When a contributor starts new website planning, Then they treat that implementation as superseded history rather than as the active build base.
2. Given a contributor needs to plan a new website slice, When they begin the work, Then they first identify base pages, sections, or components from the chosen substrate before proposing custom construction.

---

User Story 2 - Preserve old task history while creating a new forward plan (Priority: P1)

A reviewer can see which older website implementation tasks no longer govern current work and which new task list now owns delivery for each continuing website spec.

Why this priority: The reset is only trustworthy if it preserves why previous work no longer applies instead of pretending the same tasks can simply be started again.

Independent Test: Review a continuing website spec and confirm that legacy implementation tasks are visibly superseded and that a separate forward-looking task list exists for the rebuild.

Acceptance Scenarios:

1. Given a website spec remains valid after the reset, When forward planning is created, Then its legacy implementation tasks stay visible as superseded history rather than being reset to unchecked.
2. Given a reviewer inspects a continuing website spec, When they compare old and new planning, Then they can distinguish the legacy task record from the rebuild task list without relying on tribal knowledge.

---

User Story 3 - Allow bounded exceptions only when the base primitives are insufficient (Priority: P2)

A website planner can introduce a non-standard page, section, or component only after documenting why the existing base primitives cannot satisfy a continuing website spec.

Why this priority: The rebuild only stays disciplined if custom work is a bounded exception rather than the silent default.

Independent Test: Inspect any proposed custom primitive during replanning and confirm that it points to a missing candidate, a specific unmet requirement, and a dedicated exception record.

Acceptance Scenarios:

1. Given no adequate base primitive satisfies a continuing website spec, When a planner proposes custom work, Then they create a documented exception tied to that unmet requirement.
2. Given an adequate base primitive exists, When a planner proposes custom rebuilding anyway, Then the proposal is rejected as a default path and must return to mapping or adaptation.

Edge Cases

• What happens when an existing website spec contains both enduring public-surface truth and outdated implementation assumptions? It must be classified as partially valid, updated or supplemented as needed, and then replanned on the new base rather than treated as fully current or fully discarded.
• What happens when Spec 213 remains continuing or partially valid after classification? It must receive its own dedicated rebuild-plan artifact instead of being absorbed implicitly into Specs 214, 215, 217, or 218.
• What happens when multiple base primitives could satisfy the same spec requirement? The mapping must state the chosen candidate and rationale before task creation so later work stays traceable.
• How does the rebuild handle imported demo pages, demo sections, or demo copy that do not conform to active website specs? They must generate explicit removal or adaptation tasks instead of surviving by default.
• How does the rebuild handle a missing base primitive for a required capability? The gap must become a documented exception with a bounded replacement task rather than a silent greenfield detour.

Requirements (mandatory)

Constitution alignment (required): This feature introduces no Microsoft Graph calls, no queueing, no long-running operations, no authorization changes, and no Filament operator surfaces. Its contract is strictly local to apps/website and the planning artifacts that govern website implementation.

Constitution alignment (PROP-001 / ABSTR-001 / PERSIST-001 / STATE-001 / BLOAT-001): This feature adds a narrow website-local rebuild contract and exception workflow, not new runtime persistence or a shared platform abstraction. The rule set is justified only because a full implementation reset would otherwise blur continuing website truth, legacy task history, and forward planning.

Constitution alignment (TEST-GOV-001): This feature changes no runtime behavior and adds no automated runtime tests. Follow-up implementation specs remain responsible for build and browser validation. This spec is validated through repository review and the specification quality checklist only.

Functional Requirements

• FR-001: The existing apps/website implementation MUST be treated as discarded implementation history and MUST NOT remain the primary starting point for forward website work.
• FR-002: AstroDeck MUST become the required technical and structural substrate for new apps/website implementation work.
• FR-003: This reset-and-rebuild contract MUST remain strictly local to apps/website and MUST NOT impose platform, Filament, or cross-app obligations.
• FR-004: Existing website specs that still define valid public-surface truth MUST remain authoritative unless a later spec explicitly replaces or narrows them.
• FR-005: Each existing website spec in scope MUST be classified as continuing, partially valid, or superseded before new implementation planning begins.
• FR-006: Legacy implementation tasks tied to the discarded website MUST remain visible as historical context and MUST NOT be reset to unchecked or reopened as if the underlying implementation basis were unchanged.
• FR-007: Legacy implementation tasks affected by the rebuild MUST use the canonical historical marker superseded by AstroDeck rebuild so their non-authoritative status stays consistent across all affected website specs.
• FR-008: Each continuing or partially valid website spec MUST receive a separate new implementation plan for the rebuild; if Spec 213 remains continuing or partially valid after classification, it MUST receive its own dedicated rebuild-plan artifact rather than being folded implicitly into Specs 214, 215, 217, or 218.
• FR-009: Each new implementation plan MUST identify candidate AstroDeck pages, sections, and components that act as the starting point for that spec's rebuild work.
• FR-010: Each identified AstroDeck candidate in a new plan MUST be classified as keep, adapt, remove, or exception.
• FR-011: New implementation tasks MUST explicitly name the relevant AstroDeck page, section, component, or mapping activity rather than describing custom rebuilding in generic terms.
• FR-012: New implementation tasks MUST cover removal of demo pages, demo sections, demo components, and demo copy that do not conform to active website specs.
• FR-013: New implementation tasks MUST cover any required adaptation to structure, routing, content slots, styling, or composition needed to satisfy active website specs.
• FR-014: New implementation work MUST begin with AstroDeck primitive identification and mapping before any freeform new page, section, or component is proposed.
• FR-015: A freeform new page, section, or component MUST NOT be created when an adequate AstroDeck-derived candidate already exists; a candidate counts as adequate only when keep or bounded adaptation can satisfy the active requirement without inventing a net-new IA contract or unsupported interaction model.
• FR-016: A non-AstroDeck page, section, or component MAY be introduced only through a documented exception approved in the mapping review by a named website reviewer, owner, or equivalent feature approver and tied to a specific unmet requirement in an active website spec.
• FR-017: Each documented exception MUST record the missing AstroDeck candidate, the unmet requirement, why the available AstroDeck candidates failed the adequacy test, the bounded deviation, the named approver, and the dedicated task or planning entry that owns the exception.
• FR-018: The rebuild workflow MUST occur in this order: discard prior implementation basis, establish AstroDeck as base, inventory AstroDeck primitives, classify existing website specs, mark legacy tasks superseded, create mappings, create new tasks, document exceptions, then begin implementation.
• FR-019: The planning output for each continuing or partially valid website spec MUST include AstroDeck primitive mapping, keep/adapt/remove/exception decisions, a new task list embedded in the same per-spec mapping or disposition artifact or linked from it explicitly, and explicit acceptance mapping back to the active spec.
• FR-020: Any material change to page inventory, CTA logic, navigation, or trust messaging introduced through AstroDeck adoption MUST appear in updated existing website specs or explicitly created follow-up website specs referenced from the rebuild planning artifacts rather than entering silently through template import.
• FR-021: The rebuild deliverables MUST include an AstroDeck inventory for apps/website, a classification of in-scope website specs, preserved historical task treatment using the canonical superseded marker, a new task list or explicit supersession closure for each in-scope website spec, a material-drift follow-up record for any required spec updates, and an exception register that records approved exceptions and explicit no-exception outcomes.
• FR-022: Follow-up classification MUST explicitly evaluate the current known website spec set that already governs apps/website, including Specs 213, 214, 215, 217, and 218.
• FR-023: Task wording and planning artifacts MUST keep AstroDeck visible as the implementation substrate and MUST NOT hide it behind generic build verbs that make the mapping step invisible.

Assumptions

• This reset occurs in a pre-production website track, so preserving the discarded implementation for backward compatibility is not required.
• Existing website specs remain the current normative baseline until they are explicitly classified or superseded through follow-up planning.
• The chosen AstroDeck distribution provides reusable pages, sections, and components sufficient to support an inventory and mapping pass.

Dependencies

• AstroDeck assets and primitives must be available to the repository or local implementation workspace so that inventory and mapping can be performed.
• Follow-up planning work must create separate task lists or replanning artifacts for the continuing website specs after this reset spec is accepted.
• The planning workflow must support a visible superseded marker or equivalent notation for legacy implementation tasks.

Key Entities

• Legacy Website Implementation: The previous apps/website codebase and assembly approach that remains part of repository history but no longer serves as the forward-looking implementation base.
• Continuing Website Spec: An existing website spec whose public-surface truth remains active after classification, even though its prior implementation tasks may no longer govern delivery.
• AstroDeck Primitive Mapping: The per-spec record of which AstroDeck pages, sections, and components serve as the rebuild starting point and whether each is kept, adapted, removed, or treated as an exception.
• Superseded Legacy Task: A historical implementation task preserved for traceability but no longer authoritative for current website delivery.
• Documented Exception: A bounded approval record for introducing a non-AstroDeck page, section, or component when no adequate AstroDeck candidate satisfies an active website requirement.

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: A reviewer can inspect the reset artifacts and determine in one pass that the previous apps/website implementation no longer governs forward work.
• SC-002: 100% of continuing or partially valid website specs in scope, including Spec 213 whenever it remains active after classification, have a forward-looking rebuild task list that is clearly separated from legacy implementation tasks.
• SC-003: 100% of forward-looking website plans identify starting pages, sections, and components and assign keep, adapt, remove, or exception outcomes before implementation begins.
• SC-004: 100% of freeform non-AstroDeck primitives introduced during follow-up planning carry an explicit exception record tied to an unmet active-spec requirement.
• SC-005: 100% of the currently known website spec set in scope is classified as continuing, partially valid, or superseded before rebuild implementation starts.