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.)