TenantAtlas/specs/226-astrodeck-inventory-planning/spec.md

# Feature Specification: AstroDeck Inventory Planning for Website Rebuild

**Feature Branch**: `226-astrodeck-inventory-planning`  
**Created**: 2026-04-22  
**Status**: Draft  
**Input**: User description: "Spec 226 - apps/website AstroDeck Inventory for Strict Rebuild Planning"

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

- **Problem**: Das Team kann AstroDeck-Konformitat bei der Website-Re-Planung nicht belastbar nachweisen, weil ein systematisches Primitive-Inventar fehlt.
- **Today's failure**: AstroDeck wird unscharf referenziert, Kandidaten werden opportunistisch gewahlt, und wichtige oder unpassende Primitives bleiben unsichtbar.
- **User-visible improvement**: Folge-Specs und Rebuild-Tasks werden konsistent, nachvollziehbar und auditierbar, weil jede Auswahl auf dokumentierten Kandidaten basiert.
- **Smallest enterprise-capable version**: Ein vollstandiges, referenzierbares Inventory fur Pages, Sections und Components mit einheitlicher Klassifikation, Eignung und Risiko-Sichtbarkeit.
- **Explicit non-goals**: Keine finale Primitive-Auswahl je TenantAtlas-Seite, keine Umsetzung von UI-Seiten, keine Copy-Arbeit, keine Plattform- oder Backend-Themen.
- **Permanent complexity imported**: Neue Inventar-Taxonomie (Primitive Class, Suitability Class, Relevance, Markierungen) und Pflegeaufwand fur die Inventardokumentation.
- **Why now**: Nach dem AstroDeck-Bindungsentscheid muss vor jedem weiteren Mapping die verfugbare Primitive-Landschaft explizit gemacht werden, sonst droht Greenfield-Drift.
- **Why not local**: Eine schmale lokale Notiz lost weder die Vollstandigkeitsanforderung noch die Wiederverwendbarkeit fur Folge-Specs und Task-Planung.
- **Approval class**: Core Enterprise
- **Red flags triggered**: Scope creep in Mapping-Phase; verdeckte Ausnahmen ohne Inventarspur.
- **Score**: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitat: 1 | Produktnahe: 2 | Wiederverwendung: 2 | **Gesamt: 11/12**
- **Decision**: approve

## Spec Scope Fields *(mandatory)*

- **Scope**: workspace
- **Primary Routes**: Keine runtime-Route-Anderung; betroffen sind Website-Rebuild-Planungsartefakte fur `apps/website`.
- **Data Ownership**: Repository-Dokumentation auf Workspace-Ebene; keine tenant-owned Records.
- **RBAC**: N/A - keine Laufzeit- oder Berechtigungsanderung.

For canonical-view specs, the spec MUST define:

- **Default filter behavior when tenant-context is active**: N/A
- **Explicit entitlement checks preventing cross-tenant leakage**: N/A

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

N/A - no operator-facing surface change

| Surface / Change | Operator-facing surface change? | Native vs Custom | Shared-Family Relevance | State Layers Touched | Exception Needed? | Low-Impact / `N/A` Note |
|---|---|---|---|---|---|---|
| AstroDeck inventory documentation for `apps/website` | no | N/A | none | none | no | `N/A - planning artifact only` |

## Decision-First Surface Role *(mandatory when operator-facing surfaces are changed)*

N/A - no operator-facing surface change

## UI/UX Surface Classification *(mandatory when operator-facing surfaces are changed)*

N/A - no operator-facing surface change

## Operator Surface Contract *(mandatory when operator-facing surfaces are changed)*

N/A - no operator-facing surface change

## Proportionality Review *(mandatory when structural complexity is introduced)*

- **New source of truth?**: no
- **New persisted entity/table/artifact?**: no
- **New abstraction?**: no
- **New enum/state/reason family?**: no
- **New cross-domain UI framework/taxonomy?**: yes (Dokumentations-Taxonomie fur Inventarbewertung)
- **Current operator problem**: Teams konnen Rebuild-Entscheidungen nicht konsistent begrunden, weil AstroDeck-Kandidaten nicht vollstandig sichtbar sind.
- **Existing structure is insufficient because**: Bestehende Spezifikationen beschreiben Ziele und Seiten, aber nicht die vollstandige Primitive-Ausgangslage.
- **Narrowest correct implementation**: Ein verpflichtendes Inventar mit klaren Pflichtattributen, Eignungsklassen und Markierungen ohne Implementierungsentscheidungen.
- **Ownership cost**: Laufender Aufwand fur Pflege und Aktualisierung des Inventars vor Folge-Mappings.
- **Alternative intentionally rejected**: Ad-hoc Mapping ohne Inventar, weil es zu intransparenter Auswahl und hoher Rework-Wahrscheinlichkeit fuhrt.
- **Release truth**: Current-release truth

### Compatibility posture

This feature assumes a pre-production environment.

Backward compatibility, legacy aliases, migration shims, historical fixtures, and compatibility-specific tests are out of scope unless explicitly required by this spec.

Canonical replacement is preferred over preservation.

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

- **Test purpose / classification**: N/A (Spezifikations- und Planungsarbeit ohne Runtime-Anderung)
- **Validation lane(s)**: N/A
- **Why this classification and these lanes are sufficient**: Die Anderung erzeugt keine ausfuhrbare Laufzeitlogik; Qualitat wird uber Spezifikationsvollstandigkeit und Checkliste validiert.
- **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**: ordinary feature coverage only
- **Reviewer handoff**: Reviewer bestatigen Vollstandigkeit des Inventarrahmens, fehlende Implementierungsdetails und messbare Erfolgskriterien.
- **Budget / baseline / trend impact**: none
- **Escalation needed**: none
- **Active feature PR close-out entry**: Guardrail
- **Planned validation commands**: none (Dokumentenreview)

## User Scenarios & Testing *(mandatory)*

### User Story 1 - Vollstandiges Primitive-Inventar erstellen (Priority: P1)

Als Planungsverantwortliche Person fur den Website-Rebuild will ich eine vollstandige Liste der verfugbaren AstroDeck Pages, Sections und Components haben, damit ich jede nachgelagerte Mapping-Entscheidung auf nachweisbarer Verfugbarkeit basieren kann.

**Why this priority**: Ohne Vollstandigkeit ist jede weitere Re-Planung fachlich unsicher und nicht AstroDeck-konform.

**Independent Test**: Kann eigenstandig gepruft werden, indem die drei Inventarlisten vorliegen und jeder Eintrag die Pflichtattribute enthalt.

**Acceptance Scenarios**:

1. **Given** eine AstroDeck-basierte Re-Planung startet, **When** das Inventar erstellt wird, **Then** existieren getrennte und dokumentierte Listen fur Pages, Sections und Components.
2. **Given** ein Inventareintrag wird gepruft, **When** Pflichtattribute kontrolliert werden, **Then** sind Identifier, Primitive Class, Functional Role, Default Semantics, Default Visual Character, TenantAtlas Relevance und Suitability Class vorhanden.

---

### User Story 2 - Kandidaten und Risiken sichtbar machen (Priority: P1)

Als Spezifikationsverantwortliche Person will ich starke, anpassbare, schwache und ungeeignete Kandidaten inklusive Risiko-Markierungen sehen, damit die Folge-Specs transparent begrundete Auswahlentscheidungen treffen konnen.

**Why this priority**: Sichtbarkeit von Risiken und Nicht-Kandidaten verhindert verzerrte Auswahl und verdeckte Auslassungen.

**Independent Test**: Kann eigenstandig gepruft werden, indem die Suitability-Distribution und Risiko-Markierungen im Inventar nachvollziehbar ausgewiesen sind.

**Acceptance Scenarios**:

1. **Given** das Inventar liegt vor, **When** die Eignung gepruft wird, **Then** jeder Eintrag ist einer Klasse A bis D zugeordnet.
2. **Given** semantisch oder visuell riskante Primitives existieren, **When** das Inventar gelesen wird, **Then** diese sind explizit markiert statt stillschweigend entfernt.

---

### User Story 3 - Folge-Specs belastbar vorbereiten (Priority: P3)

Als Autorin oder Autor nachgelagerter Mapping-Specs will ich auf das Inventory referenzieren konnen, damit neue Tasks und Ausnahmen konsistent, wiederholbar und auditierbar geplant werden.

**Why this priority**: Der Nutzen des Inventars entsteht erst, wenn Folge-Specs es als verpflichtende Grundlage verwenden.

**Independent Test**: Kann eigenstandig gepruft werden, indem Folge-Specs eindeutige Inventarreferenzen fur Auswahl- und Ausnahmeentscheidungen nutzen.

**Acceptance Scenarios**:

1. **Given** eine Folge-Spec wird erstellt, **When** Primitive-Mapping dokumentiert wird, **Then** die Entscheidung verweist auf konkrete Inventareintrage und deren Eignung.

### Edge Cases

- Was passiert, wenn ein AstroDeck-Primitive mehrdeutig zwischen Section und Component einzuordnen ist? Es MUSS eine klare Primarklasse dokumentiert und die Mehrdeutigkeit im Eintrag vermerkt werden.
- Was passiert, wenn eine vermeintlich irrelevante Demo-Seite spater als Vorlage nutzbar ist? Sie MUSS trotzdem inventarisiert werden und darf nicht durch vorzeitiges Filtering verloren gehen.
- Was passiert, wenn in kurzer Zeit neue AstroDeck-Primitives hinzugefugt werden? Das Inventar MUSS vor nachsten Mapping-Entscheidungen aktualisiert werden.

### Assumptions & Dependencies

- Die AstroDeck-Bindung fur den Website-Rebuild gilt bereits als gesetzt (Referenz: vorangehender Bindungsentscheid).
- Folge-Specs fur Mapping und Task-Planung konsumieren das Inventory als verpflichtende Eingabe.
- Inventarisierung bezieht sich strikt auf den Scope `apps/website` und schlieBt Plattform-Surfaces aus.

## Requirements *(mandatory)*

**Constitution alignment (required):** Nicht anwendbar, da keine Microsoft-Graph-Aufrufe, keine Runtime-Mutation und keine long-running Operations eingefuhrt werden.

**Constitution alignment (PROP-001 / ABSTR-001 / PERSIST-001 / STATE-001 / BLOAT-001):** Nur Dokumentations-Taxonomie; keine neue Laufzeitpersistenz, keine Runtime-Abstraktionsschicht, keine neuen produktiven Zustandsmaschinen.

**Constitution alignment (TEST-GOV-001):** Runtime-Tests nicht erforderlich; der Nachweis erfolgt uber Vollstandigkeit, Eindeutigkeit und Messbarkeit der Spezifikationsartefakte.

**Constitution alignment (OPS-UX):** N/A

**Constitution alignment (RBAC-UX):** N/A

**Constitution alignment (OPS-EX-AUTH-001):** N/A

**Constitution alignment (BADGE-001):** N/A

**Constitution alignment (UI-FIL-001):** N/A

**Constitution alignment (UI-NAMING-001):** N/A

**Constitution alignment (DECIDE-001):** N/A

**Constitution alignment (UI-CONST-001 / UI-SURF-001 / ACTSURF-001 / UI-HARD-001 / UI-EX-001 / UI-REVIEW-001 / HDR-001):** N/A

**Constitution alignment (ACTSURF-001 - action hierarchy):** N/A

**Constitution alignment (OPSURF-001):** N/A

**Constitution alignment (UI-SEM-001 / LAYER-001 / TEST-TRUTH-001):** N/A

**Constitution alignment (Filament Action Surfaces):** N/A

**Constitution alignment (UX-001 — Layout & Information Architecture):** N/A

### Functional Requirements

- **FR-001**: Das System der Rebuild-Planung MUSS vor jeder AstroDeck-basierten Re-Planung von `apps/website` ein dokumentiertes Inventory fur Pages, Sections und Components verlangen. Das Inventory MUSS als strukturierte, repository-referenzierbare Dokumentation vorliegen; rein implizites Wissen oder unstrukturierte Screenshots sind ausgeschlossen.
- **FR-002**: Das Inventory MUSS fur jeden Eintrag mindestens Identifier, Primitive Class, Functional Role, Default Semantics, Default Visual Character, TenantAtlas Relevance und Suitability Class enthalten.
- **FR-003**: Das Inventory MUSS Pages, Sections und Components als getrennte Klassen dokumentieren und als eigenstandige Listen auswertbar machen.
- **FR-004**: Das Inventory MUSS pro Eintrag eine vorlaufige Eignung in Klasse A, B, C oder D enthalten.
- **FR-005**: Das Inventory MUSS auch ungeeignete, risikoreiche oder demo-only Primitives sichtbar halten und darf diese nicht stillschweigend auslassen.
- **FR-006**: Das Inventory MUSS TenantAtlas-Relevanz pro Eintrag als hohe, mittlere, geringe oder keine Relevanz erfassen.
- **FR-007**: Das Inventory MUSS die Candidate Visibility fur Homepage, Hero, Product, Trust, Changelog, Contact/Demo, Navigation und Footer explizit ausweisbar machen.
- **FR-008**: Das Inventory MUSS eine dokumentierte Bewertungslogik enthalten, die Struktur, Semantik, Rework-Aufwand, Risiko und Reuse-Potenzial je Primitive berucksichtigt.
- **FR-009**: Folge-Specs fur Mapping und Task-Planung MUSSEN auf das Inventory als verpflichtende Referenz verweisen.

## UI Action Matrix *(mandatory when Filament is changed)*

N/A - no Filament surface change.

### Key Entities *(include if feature involves data)*

- **Inventory Entry**: Ein dokumentierter AstroDeck-Primitive-Eintrag mit Pflichtattributen, Eignungsklasse, Relevanz und optionalen Markierungen.
- **Primitive Class**: Kategorie eines Inventareintrags (`Page`, `Section`, `Component`) zur strukturierten Trennung und Auswertung.
- **Suitability Class**: Vorlaufige Eignungsstufe (`A`, `B`, `C`, `D`) fur TenantAtlas-Nutzbarkeit.
- **Marker Set**: Optionales Tag-Set pro Eintrag (z. B. `tenantatlas-likely`, `visual-risk`, `demo-only`) zur besseren Mapping-Qualitat.

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-001**: 100% der im Scope identifizierten AstroDeck-Primitives sind in genau einer der drei Inventarklassen (`Page`, `Section`, `Component`) dokumentiert.
- **SC-002**: 100% der Inventareintrage enthalten alle Pflichtattribute gemaB FR-002 ohne fehlende Felder.
- **SC-003**: 100% der Inventareintrage enthalten eine Suitability Class (`A` bis `D`) und eine TenantAtlas-Relevanzstufe.
- **SC-004**: Fur alle definierten Kernsurfaces (Homepage, Hero, Product, Trust, Changelog, Contact/Demo, Navigation, Footer) existiert sichtbare Kandidatenzuordnung oder explizite Nichtverfugbarkeitsnotiz.
- **SC-005**: Jede nachgelagerte Mapping-Spec referenziert mindestens einen konkreten Inventareintrag als Entscheidungsgrundlage. *(Forward-governance rule: verified in downstream mapping specs, not a done-criterion for Spec 226 itself.)*