From 68faa27cd7265f9f49aedf95654a240cc1a53544 Mon Sep 17 00:00:00 2001 From: Ahmed Darrazi Date: Wed, 22 Apr 2026 11:12:40 +0200 Subject: [PATCH] spec: finalize 226 inventory planning artifacts --- .github/agents/copilot-instructions.md | 10 +- .../checklists/requirements.md | 35 ++ .../astrodeck-inventory.logical.openapi.yaml | 287 ++++++++++++ .../data-model.md | 103 +++++ .../inventory/catalog.md | 87 ++++ .../inventory/components.md | 431 ++++++++++++++++++ .../inventory/mapping-anchors.md | 39 ++ .../inventory/pages.md | 187 ++++++++ .../inventory/sections.md | 117 +++++ .../inventory/summary.md | 41 ++ .../226-astrodeck-inventory-planning/plan.md | 187 ++++++++ .../quickstart.md | 114 +++++ .../research.md | 56 +++ .../226-astrodeck-inventory-planning/spec.md | 214 +++++++++ .../226-astrodeck-inventory-planning/tasks.md | 123 +++++ 15 files changed, 2026 insertions(+), 5 deletions(-) create mode 100644 specs/226-astrodeck-inventory-planning/checklists/requirements.md create mode 100644 specs/226-astrodeck-inventory-planning/contracts/astrodeck-inventory.logical.openapi.yaml create mode 100644 specs/226-astrodeck-inventory-planning/data-model.md create mode 100644 specs/226-astrodeck-inventory-planning/inventory/catalog.md create mode 100644 specs/226-astrodeck-inventory-planning/inventory/components.md create mode 100644 specs/226-astrodeck-inventory-planning/inventory/mapping-anchors.md create mode 100644 specs/226-astrodeck-inventory-planning/inventory/pages.md create mode 100644 specs/226-astrodeck-inventory-planning/inventory/sections.md create mode 100644 specs/226-astrodeck-inventory-planning/inventory/summary.md create mode 100644 specs/226-astrodeck-inventory-planning/plan.md create mode 100644 specs/226-astrodeck-inventory-planning/quickstart.md create mode 100644 specs/226-astrodeck-inventory-planning/research.md create mode 100644 specs/226-astrodeck-inventory-planning/spec.md create mode 100644 specs/226-astrodeck-inventory-planning/tasks.md diff --git a/.github/agents/copilot-instructions.md b/.github/agents/copilot-instructions.md index e1574f82..c95bf526 100644 --- a/.github/agents/copilot-instructions.md +++ b/.github/agents/copilot-instructions.md @@ -234,6 +234,9 @@ ## Active Technologies - File-based route files, Astro content collections under `src/content`, public assets, and planning documents under `specs/223-astrodeck-website-rebuild`; no database (223-astrodeck-website-rebuild) - PHP 8.4.15, Laravel 12, Filament v5, Livewire v4, Blade + Laravel notifications (`database` channel), Filament database notifications, `Finding`, `FindingWorkflowService`, `FindingSlaPolicy`, `AlertRule`, `AlertDelivery`, `AlertDispatchService`, `EvaluateAlertsJob`, `CapabilityResolver`, `WorkspaceContext`, `TenantMembership`, `FindingResource` (224-findings-notifications-escalation) - PostgreSQL via existing `findings`, `alert_rules`, `alert_deliveries`, `notifications`, `tenant_memberships`, and `audit_logs`; no schema changes planned (224-findings-notifications-escalation) +- Markdown artifacts + Astro 6.0.0 + TypeScript 5.9 context for source discovery + Repository spec workflow (`.specify`), Astro website source tree under `apps/website/src`, existing component taxonomy (`primitives`, `content`, `sections`, `layout`) (226-astrodeck-inventory-planning) +- Filesystem only (`specs/226-astrodeck-inventory-planning/*`) (226-astrodeck-inventory-planning) +- Filesystem only (`specs/226-astrodeck-inventory-planning/*`) (226-astrodeck-inventory-planning) - PHP 8.4.15 (feat/005-bulk-operations) @@ -268,11 +271,8 @@ ## Code Style PHP 8.4.15: Follow standard conventions ## Recent Changes -- 223-astrodeck-website-rebuild: Added TypeScript 5.9, Astro 6, Node.js 20+ + Astro, astro-icon, Tailwind CSS v4, Playwright 1.59 -- 224-findings-notifications-escalation: Added PHP 8.4.15, Laravel 12, Filament v5, Livewire v4, Blade + Laravel notifications (`database` channel), Filament database notifications, `Finding`, `FindingWorkflowService`, `FindingSlaPolicy`, `AlertRule`, `AlertDelivery`, `AlertDispatchService`, `EvaluateAlertsJob`, `CapabilityResolver`, `WorkspaceContext`, `TenantMembership`, `FindingResource` -- 222-findings-intake-team-queue: Added PHP 8.4.15, Laravel 12, Filament v5, Livewire v4, Blade + Filament admin pages/tables/actions/notifications, `Finding`, `FindingResource`, `FindingWorkflowService`, `FindingPolicy`, `CapabilityResolver`, `CanonicalAdminTenantFilterState`, `CanonicalNavigationContext`, `WorkspaceContext`, and `UiEnforcement` -- 221-findings-operator-inbox: Added PHP 8.4.15, Laravel 12, Filament v5, Livewire v4, Blade + Filament admin panel pages, `Finding`, `FindingResource`, `WorkspaceOverviewBuilder`, `WorkspaceContext`, `WorkspaceCapabilityResolver`, `CapabilityResolver`, `CanonicalAdminTenantFilterState`, and `CanonicalNavigationContext` -- 220-governance-run-summaries: Added PHP 8.4.15, Laravel 12, Filament v5, Livewire v4, Blade + Filament v5, Livewire v4, Pest v4, Laravel Sail, `TenantlessOperationRunViewer`, `OperationRunResource`, `ArtifactTruthPresenter`, `OperatorExplanationBuilder`, `ReasonPresenter`, `OperationUxPresenter`, `SummaryCountsNormalizer`, and the existing enterprise-detail builders +- 226-astrodeck-inventory-planning: Added Markdown artifacts + Astro 6.0.0 + TypeScript 5.9 context for source discovery + Repository spec workflow (`.specify`), Astro website source tree under `apps/website/src`, existing component taxonomy (`primitives`, `content`, `sections`, `layout`) +- 226-astrodeck-inventory-planning: Added Markdown artifacts + Astro 6.0.0 + TypeScript 5.9 context for source discovery + Repository spec workflow (`.specify`), Astro website source tree under `apps/website/src`, existing component taxonomy (`primitives`, `content`, `sections`, `layout`) ### Pre-production compatibility check diff --git a/specs/226-astrodeck-inventory-planning/checklists/requirements.md b/specs/226-astrodeck-inventory-planning/checklists/requirements.md new file mode 100644 index 00000000..12c69f44 --- /dev/null +++ b/specs/226-astrodeck-inventory-planning/checklists/requirements.md @@ -0,0 +1,35 @@ +# Specification Quality Checklist: AstroDeck Inventory Planning for Website Rebuild + +**Purpose**: Validate specification completeness and quality before proceeding to planning +**Created**: 2026-04-22 +**Feature**: [spec.md](../spec.md) + +## Content Quality + +- [x] No implementation details (languages, frameworks, APIs) +- [x] Focused on user value and business needs +- [x] Written for non-technical stakeholders +- [x] All mandatory sections completed + +## Requirement Completeness + +- [x] No [NEEDS CLARIFICATION] markers remain +- [x] Requirements are testable and unambiguous +- [x] Success criteria are measurable +- [x] Success criteria are technology-agnostic (no implementation details) +- [x] All acceptance scenarios are defined +- [x] Edge cases are identified +- [x] Scope is clearly bounded +- [x] Dependencies and assumptions identified + +## Feature Readiness + +- [x] All functional requirements have clear acceptance criteria +- [x] User scenarios cover primary flows +- [x] Feature meets measurable outcomes defined in Success Criteria +- [x] No implementation details leak into specification + +## Notes + +- Validation passed in first iteration; no unresolved issues. +- Ready for `/speckit.plan`. diff --git a/specs/226-astrodeck-inventory-planning/contracts/astrodeck-inventory.logical.openapi.yaml b/specs/226-astrodeck-inventory-planning/contracts/astrodeck-inventory.logical.openapi.yaml new file mode 100644 index 00000000..04b83943 --- /dev/null +++ b/specs/226-astrodeck-inventory-planning/contracts/astrodeck-inventory.logical.openapi.yaml @@ -0,0 +1,287 @@ +openapi: 3.1.0 +info: + title: AstroDeck Inventory Logical Contract + version: 0.1.0 + description: >- + Logical planning contract for publishing and querying AstroDeck primitive inventory + used by website rebuild mapping specs. This contract defines artifact shapes only + for planning governance and does not imply runtime implementation in this feature. +servers: + - url: https://planning.local +paths: + /inventory/catalogs: + post: + summary: Publish a new inventory catalog snapshot + operationId: publishInventoryCatalog + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/InventoryCatalogCreateRequest' + responses: + '201': + description: Catalog created + content: + application/json: + schema: + $ref: '#/components/schemas/InventoryCatalog' + /inventory/catalogs/{catalogId}: + get: + summary: Retrieve one inventory catalog with entries + operationId: getInventoryCatalog + parameters: + - name: catalogId + in: path + required: true + schema: + type: string + responses: + '200': + description: Catalog found + content: + application/json: + schema: + $ref: '#/components/schemas/InventoryCatalog' + /inventory/catalogs/{catalogId}/summary: + get: + summary: Retrieve suitability and risk summary + operationId: getInventorySuitabilitySummary + parameters: + - name: catalogId + in: path + required: true + schema: + type: string + responses: + '200': + description: Summary found + content: + application/json: + schema: + $ref: '#/components/schemas/SuitabilitySummary' + /inventory/catalogs/{catalogId}/entries: + get: + summary: List inventory entries with optional filters + operationId: listInventoryEntries + parameters: + - name: catalogId + in: path + required: true + schema: + type: string + - name: primitiveClass + in: query + required: false + schema: + $ref: '#/components/schemas/PrimitiveClass' + - name: suitabilityClass + in: query + required: false + schema: + $ref: '#/components/schemas/SuitabilityClass' + - name: marker + in: query + required: false + schema: + $ref: '#/components/schemas/Marker' + responses: + '200': + description: Entries returned + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/InventoryEntry' + required: [data] +components: + schemas: + PrimitiveClass: + type: string + enum: [Page, Section, Component] + SuitabilityClass: + type: string + enum: [A, B, C, D] + TenantAtlasRelevance: + type: string + enum: [high, medium, low, none] + Marker: + type: string + enum: + - tenantatlas-likely + - needs-heavy-adaptation + - visual-risk + - semantic-risk + - demo-only + - remove-likely + - hero-candidate + - trust-candidate + - navigation-candidate + - footer-candidate + - contact-candidate + - product-explainer-candidate + - changelog-candidate + InventoryEntry: + type: object + required: + - entryId + - identifier + - primitiveClass + - fileRef + - functionalRole + - defaultSemantics + - defaultVisualCharacter + - tenantatlasRelevance + - suitabilityClass + properties: + entryId: + type: string + identifier: + type: string + primitiveClass: + $ref: '#/components/schemas/PrimitiveClass' + fileRef: + type: string + functionalRole: + type: string + defaultSemantics: + type: string + defaultVisualCharacter: + type: string + tenantatlasRelevance: + $ref: '#/components/schemas/TenantAtlasRelevance' + suitabilityClass: + $ref: '#/components/schemas/SuitabilityClass' + markers: + type: array + items: + $ref: '#/components/schemas/Marker' + notes: + type: string + SuitabilitySummary: + type: object + required: + - countA + - countB + - countC + - countD + - riskVisualCount + - riskSemanticCount + - demoOnlyCount + - surfaceCandidates + properties: + countA: + type: integer + minimum: 0 + countB: + type: integer + minimum: 0 + countC: + type: integer + minimum: 0 + countD: + type: integer + minimum: 0 + riskVisualCount: + type: integer + minimum: 0 + riskSemanticCount: + type: integer + minimum: 0 + demoOnlyCount: + type: integer + minimum: 0 + surfaceCandidates: + type: object + required: + - homepage + - hero + - product + - trust + - changelog + - contactDemo + - navigation + - footer + properties: + homepage: + type: array + items: + type: string + hero: + type: array + items: + type: string + product: + type: array + items: + type: string + trust: + type: array + items: + type: string + changelog: + type: array + items: + type: string + contactDemo: + type: array + items: + type: string + navigation: + type: array + items: + type: string + footer: + type: array + items: + type: string + InventoryCatalog: + type: object + required: + - catalogId + - scope + - createdAt + - sourceCommit + - status + - entries + - summary + properties: + catalogId: + type: string + scope: + type: string + const: apps/website + createdAt: + type: string + format: date-time + sourceCommit: + type: string + status: + type: string + enum: [draft, reviewed, baselined] + entries: + type: array + items: + $ref: '#/components/schemas/InventoryEntry' + summary: + $ref: '#/components/schemas/SuitabilitySummary' + InventoryCatalogCreateRequest: + type: object + required: + - catalogId + - sourceCommit + - entries + properties: + catalogId: + type: string + sourceCommit: + type: string + entries: + type: array + minItems: 1 + items: + $ref: '#/components/schemas/InventoryEntry' diff --git a/specs/226-astrodeck-inventory-planning/data-model.md b/specs/226-astrodeck-inventory-planning/data-model.md new file mode 100644 index 00000000..30643893 --- /dev/null +++ b/specs/226-astrodeck-inventory-planning/data-model.md @@ -0,0 +1,103 @@ +# Data Model: AstroDeck Inventory Planning (Website) + +## Overview + +This feature introduces no database schema. The model defines planning artifacts that describe AstroDeck primitive availability in `apps/website`. + +## Entities + +### InventoryCatalog + +- **Purpose**: Canonical inventory container for one website planning baseline. +- **Fields**: + - `catalog_id` (string, format: `astrodeck-v`, e.g. `astrodeck-v2026-04-22`; use `astrodeck-226-baseline` for the first Spec 226 catalog) + - `scope` (fixed: `apps/website`) + - `created_at` (ISO datetime) + - `source_commit` (git SHA or reference) + - `status` (`draft`, `reviewed`, `baselined`) +- **Relationships**: + - Has many `InventoryEntry` + - Has one `SuitabilitySummary` +- **Validation rules**: + - Must include entries for all three primitive classes. + - Cannot reach `baselined` unless every entry has required attributes and suitability. + +### InventoryEntry + +- **Purpose**: One documented AstroDeck primitive candidate. +- **Fields**: + - `entry_id` (string, unique within catalog) + - `identifier` (human-readable or technical name) + - `primitive_class` (`Page`, `Section`, `Component`) + - `file_ref` (workspace-relative path) + - `functional_role` (string) + - `default_semantics` (string) + - `default_visual_character` (closed enum: `minimal` | `enterprise-neutral` | `content-heavy` | `bold-visual` | `utility-dense` | `decorative`; add `notes` for anything outside this set) + - `tenantatlas_relevance` (`high`, `medium`, `low`, `none`) + - `suitability_class` (`A`, `B`, `C`, `D`) + - `markers` (string array) + - `notes` (optional string) +- **Relationships**: + - Belongs to `InventoryCatalog` +- **Validation rules**: + - Required core fields must be non-empty. + - `primitive_class` and `suitability_class` values are constrained. + - `markers` must come from allowed marker vocabulary. + +### SuitabilitySummary + +- **Purpose**: Aggregated view of candidate distribution and risk visibility. +- **Fields**: + - `count_a`, `count_b`, `count_c`, `count_d` (integers) + - `risk_visual_count` (integer) + - `risk_semantic_count` (integer) + - `demo_only_count` (integer) + - `surface_candidates` (object keyed by surface: homepage, hero, product, trust, changelog, contact-demo, navigation, footer) +- **Relationships**: + - Belongs to `InventoryCatalog` +- **Validation rules**: + - Aggregate counts must reconcile with `InventoryEntry` rows. + - Every required surface key must be present. + +### MarkerVocabulary + +- **Purpose**: Allowed marker set for consistent tagging. +- **Allowed values**: + - `tenantatlas-likely` + - `needs-heavy-adaptation` + - `visual-risk` + - `semantic-risk` + - `demo-only` + - `remove-likely` + - `hero-candidate` + - `trust-candidate` + - `navigation-candidate` + - `footer-candidate` + - `contact-candidate` + - `product-explainer-candidate` + - `changelog-candidate` + +## Primitive Class Mapping + +- `Page` — route entrypoints in `apps/website/src/pages/` +- `Section` — composite sections in `apps/website/src/components/sections/` +- `Component` — all reusable units across three sub-families: + - `primitives/` (structural atoms) + - `content/` (semantic content blocks) + - `layout/` (shell, navigation, footer) — **layout/ maps to `primitive_class: Component`; there is no fourth primitive class** + +## Lifecycle + +### Catalog Status Transitions + +- `draft` -> `reviewed` + - Condition: required fields complete and class coverage verified. +- `reviewed` -> `baselined` + - Condition: suitability summary reconciled and candidate/risk visibility confirmed. +- `baselined` -> `draft` + - Condition: source primitive set changes and inventory requires refresh. + +## Derived Rules + +- No mapping spec may claim candidate selection without referencing `entry_id` from the active baselined catalog. +- Non-candidates (`D`) remain first-class records and cannot be hidden from summary outputs. diff --git a/specs/226-astrodeck-inventory-planning/inventory/catalog.md b/specs/226-astrodeck-inventory-planning/inventory/catalog.md new file mode 100644 index 00000000..3d97454d --- /dev/null +++ b/specs/226-astrodeck-inventory-planning/inventory/catalog.md @@ -0,0 +1,87 @@ +# AstroDeck Inventory Catalog + +- catalog_id: astrodeck-226-baseline +- scope: apps/website +- created_at: 2026-04-22T07:52:32Z +- source_commit: 71f94c3afa897c00f6a8d35b63f40882ae86e348 +- status: reviewed +- source_file_count: 50 +- inventory_entry_target: 51 + +## Source Discovery + +- discovery_command: `cd apps/website && rg --files src/pages src/components/sections src/components/primitives src/components/content src/components/layout` +- discovery_commit: `71f94c3afa897c00f6a8d35b63f40882ae86e348` +- discovery_classification_rule: Each discovered file maps to exactly one primitive class from `Page`, `Section`, or `Component`. + +### Pages + +- `apps/website/src/pages/changelog.astro` +- `apps/website/src/pages/contact.astro` +- `apps/website/src/pages/imprint.astro` +- `apps/website/src/pages/index.astro` +- `apps/website/src/pages/integrations.astro` +- `apps/website/src/pages/legal.astro` +- `apps/website/src/pages/privacy.astro` +- `apps/website/src/pages/product.astro` +- `apps/website/src/pages/security-trust.astro` +- `apps/website/src/pages/sitemap.xml.ts` +- `apps/website/src/pages/solutions.astro` +- `apps/website/src/pages/terms.astro` +- `apps/website/src/pages/trust.astro` + +### Sections + +- `apps/website/src/components/sections/CTASection.astro` +- `apps/website/src/components/sections/CapabilityGrid.astro` +- `apps/website/src/components/sections/FeatureGrid.astro` +- `apps/website/src/components/sections/LogoStrip.astro` +- `apps/website/src/components/sections/OutcomeSection.astro` +- `apps/website/src/components/sections/PageHero.astro` +- `apps/website/src/components/sections/ProgressTeaser.astro` +- `apps/website/src/components/sections/TrustGrid.astro` + +### Components + +- `apps/website/src/components/primitives/Badge.astro` +- `apps/website/src/components/primitives/Button.astro` +- `apps/website/src/components/primitives/Card.astro` +- `apps/website/src/components/primitives/Cluster.astro` +- `apps/website/src/components/primitives/Container.astro` +- `apps/website/src/components/primitives/Grid.astro` +- `apps/website/src/components/primitives/Input.astro` +- `apps/website/src/components/primitives/Section.astro` +- `apps/website/src/components/primitives/SectionHeader.astro` +- `apps/website/src/components/primitives/Stack.astro` +- `apps/website/src/components/primitives/Textarea.astro` +- `apps/website/src/components/content/AudienceRow.astro` +- `apps/website/src/components/content/Callout.astro` +- `apps/website/src/components/content/ContactPanel.astro` +- `apps/website/src/components/content/DemoPrompt.astro` +- `apps/website/src/components/content/Eyebrow.astro` +- `apps/website/src/components/content/FeatureItem.astro` +- `apps/website/src/components/content/Headline.astro` +- `apps/website/src/components/content/HeroDashboard.astro` +- `apps/website/src/components/content/IntegrationBadge.astro` +- `apps/website/src/components/content/Lead.astro` +- `apps/website/src/components/content/Metric.astro` +- `apps/website/src/components/content/PrimaryCTA.astro` +- `apps/website/src/components/content/RichText.astro` +- `apps/website/src/components/content/SecondaryCTA.astro` +- `apps/website/src/components/content/TrustPrincipleCard.astro` +- `apps/website/src/components/layout/Footer.astro` +- `apps/website/src/components/layout/Navbar.astro` +- `apps/website/src/components/layout/PageShell.astro` + +## Related Layout Dependencies Outside T002 Discovery + +- `apps/website/src/layouts/BaseLayout.astro` + +BaseLayout is intentionally inventoried because T005 names it explicitly and `PageShell.astro` cannot render without it, even though the quickstart discovery command is limited to `src/pages` and `src/components/*`. + +## Reviewer Sign-off + +- reviewed_at: 2026-04-22 +- reviewer: Codex +- summary_reconciled: yes +- notes: Validated 51 entries across pages, sections, and components; suitability totals and risk counts reconcile with `summary.md`. diff --git a/specs/226-astrodeck-inventory-planning/inventory/components.md b/specs/226-astrodeck-inventory-planning/inventory/components.md new file mode 100644 index 00000000..7b4da953 --- /dev/null +++ b/specs/226-astrodeck-inventory-planning/inventory/components.md @@ -0,0 +1,431 @@ +# Component Inventory + +- catalog_id: astrodeck-226-baseline +- primitive_class: Component +- entry_count: 30 + +### Primitives + +#### component.button + +- entry_id: component.button +- identifier: Button +- primitive_class: Component +- file_ref: apps/website/src/components/primitives/Button.astro +- functional_role: Shared interaction primitive for links and buttons across CTA surfaces. +- default_semantics: Reusable primary, secondary, or ghost action control with shared size variants. +- default_visual_character: enterprise-neutral +- tenantatlas_relevance: high +- suitability_class: A +- markers: [tenantatlas-likely] +- notes: Foundational CTA primitive used throughout the site shell and surface sections. + +#### component.card + +- entry_id: component.card +- identifier: Card +- primitive_class: Component +- file_ref: apps/website/src/components/primitives/Card.astro +- functional_role: Wraps grouped content inside consistent rounded surface treatments. +- default_semantics: Generic surface container with default, accent, and subtle variants plus optional hover behavior. +- default_visual_character: enterprise-neutral +- tenantatlas_relevance: high +- suitability_class: A +- markers: [tenantatlas-likely] +- notes: Central structural primitive for nearly every section family. + +#### component.container + +- entry_id: component.container +- identifier: Container +- primitive_class: Component +- file_ref: apps/website/src/components/primitives/Container.astro +- functional_role: Constrains horizontal width and page gutters. +- default_semantics: Layout wrapper for content, measure, and wide-width surfaces. +- default_visual_character: minimal +- tenantatlas_relevance: high +- suitability_class: A +- markers: [tenantatlas-likely] +- notes: Core layout primitive that stays valid regardless of final surface composition. + +#### component.grid + +- entry_id: component.grid +- identifier: Grid +- primitive_class: Component +- file_ref: apps/website/src/components/primitives/Grid.astro +- functional_role: Provides the standard responsive card and content grid behavior. +- default_semantics: Responsive grid helper with fixed column presets and shared gap sizing. +- default_visual_character: minimal +- tenantatlas_relevance: high +- suitability_class: A +- markers: [tenantatlas-likely] +- notes: Generic layout utility already proven across product, trust, and contact surfaces. + +#### component.stack + +- entry_id: component.stack +- identifier: Stack +- primitive_class: Component +- file_ref: apps/website/src/components/primitives/Stack.astro +- functional_role: Offers vertical spacing control for simple stacked layouts. +- default_semantics: Flex-column spacing helper with small through extra-large gap presets. +- default_visual_character: minimal +- tenantatlas_relevance: medium +- suitability_class: B +- markers: [] +- notes: Useful as a narrow layout helper, but it is not currently exercised by the shipped route set. + +#### component.section + +- entry_id: component.section +- identifier: Section +- primitive_class: Component +- file_ref: apps/website/src/components/primitives/Section.astro +- functional_role: Normalizes vertical rhythm, tone, and disclosure layering for page sections. +- default_semantics: Section shell primitive with density, tone, and disclosure-layer options. +- default_visual_character: minimal +- tenantatlas_relevance: high +- suitability_class: A +- markers: [tenantatlas-likely] +- notes: Required base primitive for keeping section spacing and surface shells consistent. + +#### component.section-header + +- entry_id: component.section-header +- identifier: SectionHeader +- primitive_class: Component +- file_ref: apps/website/src/components/primitives/SectionHeader.astro +- functional_role: Standardizes eyebrow, headline, and supporting copy for section intros. +- default_semantics: Content header primitive with alignment and width controls. +- default_visual_character: enterprise-neutral +- tenantatlas_relevance: high +- suitability_class: A +- markers: [tenantatlas-likely] +- notes: Direct fit for any rebuild surface that needs consistent section framing. + +#### component.cluster + +- entry_id: component.cluster +- identifier: Cluster +- primitive_class: Component +- file_ref: apps/website/src/components/primitives/Cluster.astro +- functional_role: Groups inline items such as CTA pairs and small metadata sets. +- default_semantics: Flexible inline cluster helper with gap and justification presets. +- default_visual_character: minimal +- tenantatlas_relevance: high +- suitability_class: A +- markers: [tenantatlas-likely] +- notes: Reusable utility for CTAs, badges, and compact link groups. + +#### component.badge + +- entry_id: component.badge +- identifier: Badge +- primitive_class: Component +- file_ref: apps/website/src/components/primitives/Badge.astro +- functional_role: Applies small signal labels for eyebrows, dates, and metadata accents. +- default_semantics: Pill-style label primitive with accent, neutral, signal, and warm tones. +- default_visual_character: minimal +- tenantatlas_relevance: high +- suitability_class: A +- markers: [tenantatlas-likely] +- notes: Lightweight signaling primitive used in hero, progress, and ecosystem contexts. + +#### component.input + +- entry_id: component.input +- identifier: Input +- primitive_class: Component +- file_ref: apps/website/src/components/primitives/Input.astro +- functional_role: Provides a text-input shell for the static contact preview. +- default_semantics: Single-line form-control primitive with readonly support but no labels, validation, or submission wiring. +- default_visual_character: utility-dense +- tenantatlas_relevance: medium +- suitability_class: B +- markers: [] +- notes: Structurally reusable, but interactive contact flows would need labels, errors, and submission states layered around it. + +#### component.textarea + +- entry_id: component.textarea +- identifier: Textarea +- primitive_class: Component +- file_ref: apps/website/src/components/primitives/Textarea.astro +- functional_role: Provides a multiline text shell for the static contact preview. +- default_semantics: Multiline form-control primitive with readonly support but no validation or helper-state system. +- default_visual_character: utility-dense +- tenantatlas_relevance: medium +- suitability_class: B +- markers: [] +- notes: Reusable if the rebuild keeps a preview-only contact pattern; richer interaction would need additional semantics. + +### Content + +#### component.headline + +- entry_id: component.headline +- identifier: Headline +- primitive_class: Component +- file_ref: apps/website/src/components/content/Headline.astro +- functional_role: Provides the shared heading scale across hero, section, and card contexts. +- default_semantics: Typography primitive for display, page, section, and card-level headings. +- default_visual_character: minimal +- tenantatlas_relevance: high +- suitability_class: A +- markers: [tenantatlas-likely] +- notes: Core type primitive for the current visual system and likely any close rebuild variant. + +#### component.lead + +- entry_id: component.lead +- identifier: Lead +- primitive_class: Component +- file_ref: apps/website/src/components/content/Lead.astro +- functional_role: Renders supporting descriptive copy with a shared size scale. +- default_semantics: Body-copy primitive for hero, card, and legal-prose support text. +- default_visual_character: minimal +- tenantatlas_relevance: high +- suitability_class: A +- markers: [tenantatlas-likely] +- notes: Generic copy primitive used across every page family. + +#### component.eyebrow + +- entry_id: component.eyebrow +- identifier: Eyebrow +- primitive_class: Component +- file_ref: apps/website/src/components/content/Eyebrow.astro +- functional_role: Introduces sections and cards with compact uppercase framing labels. +- default_semantics: Small-type label primitive with accent, neutral, and signal tones. +- default_visual_character: minimal +- tenantatlas_relevance: high +- suitability_class: A +- markers: [tenantatlas-likely] +- notes: Shared content primitive that anchors information hierarchy without adding structural complexity. + +#### component.metric + +- entry_id: component.metric +- identifier: Metric +- primitive_class: Component +- file_ref: apps/website/src/components/content/Metric.astro +- functional_role: Packages hero-supporting metrics into small card surfaces. +- default_semantics: Metric card with a numeric or label-like headline, eyebrow label, and support copy. +- default_visual_character: enterprise-neutral +- tenantatlas_relevance: high +- suitability_class: A +- markers: [tenantatlas-likely, hero-candidate] +- notes: Directly useful for hero-adjacent proof or product framing when the rebuild keeps quantified support signals. + +#### component.primary-cta + +- entry_id: component.primary-cta +- identifier: PrimaryCTA +- primitive_class: Component +- file_ref: apps/website/src/components/content/PrimaryCTA.astro +- functional_role: Wraps the primary button treatment used across hero and closing CTA surfaces. +- default_semantics: Primary action wrapper with optional helper copy and size variants. +- default_visual_character: enterprise-neutral +- tenantatlas_relevance: high +- suitability_class: A +- markers: [tenantatlas-likely] +- notes: Stable CTA wrapper used across hero, progress, footer, and closing conversion surfaces. + +#### component.secondary-cta + +- entry_id: component.secondary-cta +- identifier: SecondaryCTA +- primitive_class: Component +- file_ref: apps/website/src/components/content/SecondaryCTA.astro +- functional_role: Provides the supporting secondary action pattern for route handoffs. +- default_semantics: Secondary action wrapper with optional helper text and size variants. +- default_visual_character: enterprise-neutral +- tenantatlas_relevance: high +- suitability_class: A +- markers: [tenantatlas-likely] +- notes: Pairs cleanly with the primary CTA pattern and is already part of the approved route handoff model. + +#### component.feature-item + +- entry_id: component.feature-item +- identifier: FeatureItem +- primitive_class: Component +- file_ref: apps/website/src/components/content/FeatureItem.astro +- functional_role: Renders feature or rule cards with optional iconography, metadata, and link treatment. +- default_semantics: Card-based feature explanation primitive for product, solutions, and integration rule surfaces. +- default_visual_character: enterprise-neutral +- tenantatlas_relevance: high +- suitability_class: A +- markers: [tenantatlas-likely, product-explainer-candidate] +- notes: Strong product-explainer building block for any rebuild surface that needs repeatable explanatory cards. + +#### component.callout + +- entry_id: component.callout +- identifier: Callout +- primitive_class: Component +- file_ref: apps/website/src/components/content/Callout.astro +- functional_role: Shows compact narrative or trust-supporting callouts in card form. +- default_semantics: Callout card with optional eyebrow, headline, supporting copy, and tone selection. +- default_visual_character: enterprise-neutral +- tenantatlas_relevance: high +- suitability_class: A +- markers: [tenantatlas-likely, trust-candidate] +- notes: Works well for trust or product-support narratives without demanding a new section pattern. + +#### component.rich-text + +- entry_id: component.rich-text +- identifier: RichText +- primitive_class: Component +- file_ref: apps/website/src/components/content/RichText.astro +- functional_role: Renders structured legal or policy prose as a stack of readable cards. +- default_semantics: Rich text wrapper for titled legal sections with paragraphs and optional bullet lists. +- default_visual_character: content-heavy +- tenantatlas_relevance: medium +- suitability_class: A +- markers: [tenantatlas-likely] +- notes: Strong direct-fit primitive for the retained legal and policy routes. + +#### component.trust-principle-card + +- entry_id: component.trust-principle-card +- identifier: TrustPrincipleCard +- primitive_class: Component +- file_ref: apps/website/src/components/content/TrustPrincipleCard.astro +- functional_role: Packages trust claims into a consistent proof-card treatment. +- default_semantics: Trust card with title, supporting copy, and optional note. +- default_visual_character: enterprise-neutral +- tenantatlas_relevance: high +- suitability_class: A +- markers: [tenantatlas-likely, trust-candidate] +- notes: Canonical trust-content primitive already aligned with the explicit trust posture route. + +#### component.demo-prompt + +- entry_id: component.demo-prompt +- identifier: DemoPrompt +- primitive_class: Component +- file_ref: apps/website/src/components/content/DemoPrompt.astro +- functional_role: Highlights suggested conversation prompts for the first contact exchange. +- default_semantics: Simple supporting card for contact/demo preparation prompts. +- default_visual_character: enterprise-neutral +- tenantatlas_relevance: medium +- suitability_class: B +- markers: [contact-candidate] +- notes: Useful for the contact path, but it is tied to a specific conversation-prep pattern rather than a universal route need. + +#### component.hero-dashboard + +- entry_id: component.hero-dashboard +- identifier: HeroDashboard +- primitive_class: Component +- file_ref: apps/website/src/components/content/HeroDashboard.astro +- functional_role: Supplies the product-near illustrative UI mock used in hero compositions. +- default_semantics: Decorative but content-bearing product mock that implies change history, restore preview, and review queue behavior. +- default_visual_character: bold-visual +- tenantatlas_relevance: high +- suitability_class: C +- markers: [needs-heavy-adaptation, visual-risk, hero-candidate] +- notes: The mock is strongly tied to the current TenantAtlas governance narrative and would require coordinated visual and narrative updates before reuse. + +#### component.integration-badge + +- entry_id: component.integration-badge +- identifier: IntegrationBadge +- primitive_class: Component +- file_ref: apps/website/src/components/content/IntegrationBadge.astro +- functional_role: Compresses ecosystem, partner, or integration signals into compact badge cards. +- default_semantics: Small proof card for ecosystem-fit lists and supporting strips. +- default_visual_character: enterprise-neutral +- tenantatlas_relevance: medium +- suitability_class: C +- markers: [needs-heavy-adaptation, semantic-risk] +- notes: Reusable only when the rebuild can substantiate the ecosystem claim; otherwise the component risks overstating platform breadth. + +#### component.audience-row + +- entry_id: component.audience-row +- identifier: AudienceRow +- primitive_class: Component +- file_ref: apps/website/src/components/content/AudienceRow.astro +- functional_role: Shows audience-specific fit through bullets and an optional secondary CTA. +- default_semantics: Audience-fit card primitive used on the solutions route. +- default_visual_character: enterprise-neutral +- tenantatlas_relevance: medium +- suitability_class: B +- markers: [tenantatlas-likely] +- notes: Structurally useful, but the audience framing is supporting rather than core to the first-pass route model. + +#### component.contact-panel + +- entry_id: component.contact-panel +- identifier: ContactPanel +- primitive_class: Component +- file_ref: apps/website/src/components/content/ContactPanel.astro +- functional_role: Frames qualified outreach with a short list of who should contact the team and one primary CTA. +- default_semantics: Accent card for the contact route that packages qualification points and a primary action. +- default_visual_character: enterprise-neutral +- tenantatlas_relevance: high +- suitability_class: A +- markers: [tenantatlas-likely, contact-candidate] +- notes: Directly useful for the contact and demo surface because it keeps outreach intent explicit without building a form workflow. + +### Layout + +#### component.page-shell + +- entry_id: component.page-shell +- identifier: PageShell +- primitive_class: Component +- file_ref: apps/website/src/components/layout/PageShell.astro +- functional_role: Wraps every page with SEO metadata, shell attributes, navigation, and footer. +- default_semantics: Canonical page-shell orchestrator that binds route metadata to the shared layout and shell components. +- default_visual_character: enterprise-neutral +- tenantatlas_relevance: high +- suitability_class: A +- markers: [tenantatlas-likely] +- notes: Central shell component for any rebuild that preserves the current route architecture. + +#### component.navbar + +- entry_id: component.navbar +- identifier: Navbar +- primitive_class: Component +- file_ref: apps/website/src/components/layout/Navbar.astro +- functional_role: Provides the sticky primary navigation with desktop and mobile variants. +- default_semantics: Top-level navigation shell with brand lockup, route links, and a secondary CTA. +- default_visual_character: enterprise-neutral +- tenantatlas_relevance: high +- suitability_class: A +- markers: [tenantatlas-likely, navigation-candidate] +- notes: Canonical navigation surface for the current website route set. + +#### component.footer + +- entry_id: component.footer +- identifier: Footer +- primitive_class: Component +- file_ref: apps/website/src/components/layout/Footer.astro +- functional_role: Provides the closing navigation, trustful footer copy, and final CTA. +- default_semantics: Footer surface with route-group navigation, lead copy, and a small CTA. +- default_visual_character: enterprise-neutral +- tenantatlas_relevance: high +- suitability_class: A +- markers: [tenantatlas-likely, footer-candidate] +- notes: Canonical footer surface and an explicit part of the rebuild inventory. + +#### component.base-layout + +- entry_id: component.base-layout +- identifier: BaseLayout +- primitive_class: Component +- file_ref: apps/website/src/layouts/BaseLayout.astro +- functional_role: Owns the document shell, metadata tags, font includes, and global CSS import. +- default_semantics: Top-level HTML layout wrapper for the static Astro site. +- default_visual_character: minimal +- tenantatlas_relevance: high +- suitability_class: A +- markers: [tenantatlas-likely] +- notes: Included even though it sits outside the T002 discovery command because PageShell depends on it to render any route. diff --git a/specs/226-astrodeck-inventory-planning/inventory/mapping-anchors.md b/specs/226-astrodeck-inventory-planning/inventory/mapping-anchors.md new file mode 100644 index 00000000..c56956b6 --- /dev/null +++ b/specs/226-astrodeck-inventory-planning/inventory/mapping-anchors.md @@ -0,0 +1,39 @@ +# Mapping Anchors + +## Mandatory Reference Rule + +- No downstream mapping spec may claim a keep, adapt, remove, or replace decision without citing at least one `entry_id` from the active baselined catalog. +- The active catalog for Spec 226 is `astrodeck-226-baseline` until a later refresh supersedes it. +- If a downstream spec references a section or component, it should also cite the owning page or surface context when that context changes the decision. + +## Recommended Reference Block + +Use a concrete inventory block in downstream mapping specs such as `specs/214-website-visual-foundation/`, `specs/215-website-core-pages/`, or `specs/217-homepage-structure/`: + +```md +### Inventory References + +- catalog_id: astrodeck-226-baseline +- selected_entries: + - page.product + - section.feature-grid + - component.feature-item +- suitability_basis: + - page.product: A / high + - section.feature-grid: A / high + - component.feature-item: A / high +- decision: adapt +- rationale: Keep the product-explainer structure but adjust copy hierarchy and visual density for the approved rebuild route. +``` + +## Exception Path For Non-Candidate Decisions + +- If a downstream surface has no direct candidate, write `no direct candidate` explicitly in the mapping spec and cite the closest rejected `entry_id` values plus the reason they were rejected. +- If an inventory entry is intentionally excluded, cite the `entry_id`, current `suitability_class`, and the concrete reason for exclusion instead of silently omitting it. +- If a downstream spec decides a current `A` or `B` entry should still be removed, that spec must document the higher-priority constraint that overrides the inventory suitability. + +## Refresh Rule Before The Next Mapping Cycle + +- Refresh the inventory whenever the source primitive set changes under `apps/website/src/pages`, `apps/website/src/components`, or `apps/website/src/layouts`. +- Re-run the T002 discovery command from repo root and compare the resulting file list with `inventory/catalog.md`. +- If the primitive set changes, update the row-level inventory files, reconcile `summary.md`, and set `catalog.md` back to `draft` until review completes again. diff --git a/specs/226-astrodeck-inventory-planning/inventory/pages.md b/specs/226-astrodeck-inventory-planning/inventory/pages.md new file mode 100644 index 00000000..b4e2a2c8 --- /dev/null +++ b/specs/226-astrodeck-inventory-planning/inventory/pages.md @@ -0,0 +1,187 @@ +# Page Inventory + +- catalog_id: astrodeck-226-baseline +- primitive_class: Page +- entry_count: 13 + +### page.index + +- entry_id: page.index +- identifier: index +- primitive_class: Page +- file_ref: apps/website/src/pages/index.astro +- functional_role: Homepage entrypoint that sequences the launch hero, product framing, trust, progress, and contact handoff. +- default_semantics: Primary marketing route for first-visit orientation and route handoff into product, trust, changelog, and contact. +- default_visual_character: bold-visual +- tenantatlas_relevance: high +- suitability_class: A +- markers: [tenantatlas-likely] +- notes: The current homepage already reflects the canonical TenantAtlas launch journey and is the main reference page for downstream mapping. + +### page.product + +- entry_id: page.product +- identifier: product +- primitive_class: Page +- file_ref: apps/website/src/pages/product.astro +- functional_role: Explains the connected product model before the visitor is asked to trust or contact the team. +- default_semantics: Product explainer route that combines hero framing, feature clusters, narrative callouts, and downstream CTAs. +- default_visual_character: enterprise-neutral +- tenantatlas_relevance: high +- suitability_class: A +- markers: [tenantatlas-likely, product-explainer-candidate] +- notes: Strong direct-fit route for rebuild planning because it already anchors the product explanation in current release truth. + +### page.trust + +- entry_id: page.trust +- identifier: trust +- primitive_class: Page +- file_ref: apps/website/src/pages/trust.astro +- functional_role: Dedicated trust posture route for operator safeguards, isolation boundaries, and credibility framing. +- default_semantics: Trust-first supporting page with one explicit proof surface and a clear contact handoff. +- default_visual_character: enterprise-neutral +- tenantatlas_relevance: high +- suitability_class: A +- markers: [tenantatlas-likely, trust-candidate] +- notes: This is the canonical trust route and should remain explicit in any AstroDeck rebuild plan. + +### page.changelog + +- entry_id: page.changelog +- identifier: changelog +- primitive_class: Page +- file_ref: apps/website/src/pages/changelog.astro +- functional_role: Publishes dated product progress so visitors can verify motion without relying on vague marketing claims. +- default_semantics: Content-led route with a hero, chronologically ordered update cards, and a closing CTA back into evaluation. +- default_visual_character: content-heavy +- tenantatlas_relevance: high +- suitability_class: A +- markers: [tenantatlas-likely, changelog-candidate] +- notes: The route is already aligned with the visible-progress requirement in the active website strategy. + +### page.contact + +- entry_id: page.contact +- identifier: contact +- primitive_class: Page +- file_ref: apps/website/src/pages/contact.astro +- functional_role: Qualifies outreach and shows what a serious first conversation should contain before anyone shares sensitive detail. +- default_semantics: Contact and demo-prep route with guidance cards, a static message preview, legal reassurance, and a CTA handoff. +- default_visual_character: utility-dense +- tenantatlas_relevance: high +- suitability_class: A +- markers: [tenantatlas-likely, contact-candidate] +- notes: Strong fit for rebuild planning because it already combines contact intent, legal reassurance, and route continuity. + +### page.solutions + +- entry_id: page.solutions +- identifier: solutions +- primitive_class: Page +- file_ref: apps/website/src/pages/solutions.astro +- functional_role: Shows audience fit and operating-model resonance for deeper evaluators without owning the primary journey. +- default_semantics: Supporting audience-fit route with hero framing, audience cards, supporting signals, and a closing CTA. +- default_visual_character: enterprise-neutral +- tenantatlas_relevance: medium +- suitability_class: B +- markers: [tenantatlas-likely] +- notes: Reusable with limited copy and information-architecture changes, but it should stay subordinate to the primary route set. + +### page.integrations + +- entry_id: page.integrations +- identifier: integrations +- primitive_class: Page +- file_ref: apps/website/src/pages/integrations.astro +- functional_role: Documents ecosystem fit and integration direction without pretending broad platform coverage is already launch truth. +- default_semantics: Supporting ecosystem route with badges, rule cards, and a handoff back into product or contact. +- default_visual_character: enterprise-neutral +- tenantatlas_relevance: medium +- suitability_class: B +- markers: [tenantatlas-likely] +- notes: Structurally reusable, but its value depends on keeping ecosystem claims concrete and bounded. + +### page.privacy + +- entry_id: page.privacy +- identifier: privacy +- primitive_class: Page +- file_ref: apps/website/src/pages/privacy.astro +- functional_role: Explains the narrow public-site privacy posture and the bounds of inquiry handling. +- default_semantics: Legal text route with an opening hero, reading-width rich text, and a simple next-step CTA. +- default_visual_character: content-heavy +- tenantatlas_relevance: medium +- suitability_class: B +- markers: [tenantatlas-likely] +- notes: Good structural fit for the rebuild, but the content remains jurisdiction- and policy-dependent. + +### page.terms + +- entry_id: page.terms +- identifier: terms +- primitive_class: Page +- file_ref: apps/website/src/pages/terms.astro +- functional_role: States the website terms and clarifies that public marketing pages do not replace commercial agreements. +- default_semantics: Legal text route built from hero, reading-width prose cards, and a closing CTA. +- default_visual_character: content-heavy +- tenantatlas_relevance: medium +- suitability_class: B +- markers: [tenantatlas-likely] +- notes: Directly reusable for the legal baseline, with expected copy and jurisdiction updates only. + +### page.imprint + +- entry_id: page.imprint +- identifier: imprint +- primitive_class: Page +- file_ref: apps/website/src/pages/imprint.astro +- functional_role: Publishes the public legal-notice baseline for publisher identity and jurisdiction-specific disclosure. +- default_semantics: Legal notice route with a hero, reading-width legal content, and a return CTA into trust or contact. +- default_visual_character: content-heavy +- tenantatlas_relevance: low +- suitability_class: B +- markers: [tenantatlas-likely] +- notes: Useful for the retained legal baseline, but the content remains highly dependent on jurisdiction and publication details. + +### page.legal + +- entry_id: page.legal +- identifier: legal +- primitive_class: Page +- file_ref: apps/website/src/pages/legal.astro +- functional_role: Aggregates trust, privacy, terms, and imprint into one retained legal hub route. +- default_semantics: Secondary legal index page that duplicates links to leaf legal routes and adds a short notice section. +- default_visual_character: content-heavy +- tenantatlas_relevance: low +- suitability_class: C +- markers: [needs-heavy-adaptation, semantic-risk] +- notes: The hub risks adding route ambiguity because the leaf legal pages already exist; keep only if the rebuild still needs a legal index. + +### page.security-trust + +- entry_id: page.security-trust +- identifier: security-trust +- primitive_class: Page +- file_ref: apps/website/src/pages/security-trust.astro +- functional_role: Preserves a legacy alias by redirecting `/security-trust` to `/trust`. +- default_semantics: Redirect-only route with no user-facing content surface. +- default_visual_character: minimal +- tenantatlas_relevance: low +- suitability_class: D +- markers: [] +- notes: Inventory it for route completeness, but exclude it from visual surface selection because it contributes no reusable layout or content pattern. + +### page.sitemap-xml + +- entry_id: page.sitemap-xml +- identifier: sitemap.xml +- primitive_class: Page +- file_ref: apps/website/src/pages/sitemap.xml.ts +- functional_role: Exposes a machine-readable sitemap for search crawlers. +- default_semantics: API-style XML endpoint rather than a human-facing content route. +- default_visual_character: utility-dense +- tenantatlas_relevance: none +- suitability_class: D +- markers: [] +- notes: Keep visible in the inventory for route governance, but it is not a rebuild candidate for visual or narrative surfaces. diff --git a/specs/226-astrodeck-inventory-planning/inventory/sections.md b/specs/226-astrodeck-inventory-planning/inventory/sections.md new file mode 100644 index 00000000..49bee6dc --- /dev/null +++ b/specs/226-astrodeck-inventory-planning/inventory/sections.md @@ -0,0 +1,117 @@ +# Section Inventory + +- catalog_id: astrodeck-226-baseline +- primitive_class: Section +- entry_count: 8 + +### section.page-hero + +- entry_id: section.page-hero +- identifier: PageHero +- primitive_class: Section +- file_ref: apps/website/src/components/sections/PageHero.astro +- functional_role: Renders the primary hero composition for the homepage and all secondary pages. +- default_semantics: Hero section with badge, headline, supporting copy, CTA cluster, and optional product visual or trust proof. +- default_visual_character: bold-visual +- tenantatlas_relevance: high +- suitability_class: A +- markers: [tenantatlas-likely, hero-candidate] +- notes: This is the most important rebuild primitive because it already defines homepage and subpage hero behavior in one place. + +### section.feature-grid + +- entry_id: section.feature-grid +- identifier: FeatureGrid +- primitive_class: Section +- file_ref: apps/website/src/components/sections/FeatureGrid.astro +- functional_role: Presents feature or rule clusters in a repeatable grid with a section header. +- default_semantics: Product-explainer or rule-list section that relies on structured cards rather than freeform prose. +- default_visual_character: enterprise-neutral +- tenantatlas_relevance: high +- suitability_class: A +- markers: [tenantatlas-likely, product-explainer-candidate] +- notes: Strong direct-fit section for product, solutions, and integrations surfaces. + +### section.cta-section + +- entry_id: section.cta-section +- identifier: CTASection +- primitive_class: Section +- file_ref: apps/website/src/components/sections/CTASection.astro +- functional_role: Delivers the final conversion handoff from any route back into contact or the next core page. +- default_semantics: Closing CTA band with one required primary action and one optional secondary action. +- default_visual_character: enterprise-neutral +- tenantatlas_relevance: high +- suitability_class: A +- markers: [tenantatlas-likely, contact-candidate] +- notes: It appears across the route set and already encodes the preferred evaluation handoff pattern. + +### section.capability-grid + +- entry_id: section.capability-grid +- identifier: CapabilityGrid +- primitive_class: Section +- file_ref: apps/website/src/components/sections/CapabilityGrid.astro +- functional_role: Explains the grouped product model through clustered capability cards. +- default_semantics: Product-explainer section with structured clusters, optional metadata badges, and linked supporting detail. +- default_visual_character: enterprise-neutral +- tenantatlas_relevance: high +- suitability_class: A +- markers: [tenantatlas-likely, product-explainer-candidate] +- notes: Strong fit for any rebuild surface that needs to explain how TenantAtlas capabilities connect. + +### section.outcome-section + +- entry_id: section.outcome-section +- identifier: OutcomeSection +- primitive_class: Section +- file_ref: apps/website/src/components/sections/OutcomeSection.astro +- functional_role: Frames product value through outcome cards rather than a feature checklist. +- default_semantics: Mid-page section with a header plus three outcome cards. +- default_visual_character: enterprise-neutral +- tenantatlas_relevance: high +- suitability_class: A +- markers: [tenantatlas-likely] +- notes: Useful for the homepage because it translates product truth into buyer outcomes without inflating surface complexity. + +### section.trust-grid + +- entry_id: section.trust-grid +- identifier: TrustGrid +- primitive_class: Section +- file_ref: apps/website/src/components/sections/TrustGrid.astro +- functional_role: Shows the public trust posture through structured trust-principle cards. +- default_semantics: Trust-proof section with a header and a fixed card grid. +- default_visual_character: enterprise-neutral +- tenantatlas_relevance: high +- suitability_class: A +- markers: [tenantatlas-likely, trust-candidate] +- notes: Canonical trust section for both the homepage trust block and the dedicated trust route. + +### section.logo-strip + +- entry_id: section.logo-strip +- identifier: LogoStrip +- primitive_class: Section +- file_ref: apps/website/src/components/sections/LogoStrip.astro +- functional_role: Displays ecosystem-fit badges or logo-like entries in a compact supporting strip. +- default_semantics: Supporting proof section that compresses partner, ecosystem, or integration signals into a narrow banner treatment. +- default_visual_character: decorative +- tenantatlas_relevance: medium +- suitability_class: C +- markers: [needs-heavy-adaptation, semantic-risk] +- notes: The pattern is reusable only when ecosystem proof is concrete; otherwise it risks overstating breadth and slipping into decorative social proof. + +### section.progress-teaser + +- entry_id: section.progress-teaser +- identifier: ProgressTeaser +- primitive_class: Section +- file_ref: apps/website/src/components/sections/ProgressTeaser.astro +- functional_role: Surfaces recent dated progress entries and links back to the full changelog. +- default_semantics: Changelog teaser section with compact dated cards and one follow-up CTA. +- default_visual_character: utility-dense +- tenantatlas_relevance: high +- suitability_class: A +- markers: [tenantatlas-likely, changelog-candidate] +- notes: Directly aligned with the visible-progress requirement for the current website strategy. diff --git a/specs/226-astrodeck-inventory-planning/inventory/summary.md b/specs/226-astrodeck-inventory-planning/inventory/summary.md new file mode 100644 index 00000000..b0b20b84 --- /dev/null +++ b/specs/226-astrodeck-inventory-planning/inventory/summary.md @@ -0,0 +1,41 @@ +# Suitability Summary + +- catalog_id: astrodeck-226-baseline +- reconciled_entry_count: 51 + +## Suitability Distribution + +| Class | Count | +|-------|-------| +| A | 35 | +| B | 10 | +| C | 4 | +| D | 2 | + +## Risk Visibility + +| Marker | Count | Entry IDs | +|--------|-------|-----------| +| `visual-risk` | 1 | `component.hero-dashboard` | +| `semantic-risk` | 3 | `page.legal`, `section.logo-strip`, `component.integration-badge` | +| `demo-only` | 0 | `none` | + +## Surface Candidate Visibility + +| Surface | Candidate entry_ids | Notes | +|---------|---------------------|-------| +| homepage | `page.index`, `section.page-hero`, `section.outcome-section`, `section.capability-grid`, `section.trust-grid`, `section.progress-teaser`, `section.cta-section` | Current MarkerVocabulary has no dedicated `homepage-candidate` tag, so homepage visibility is tracked in this summary only. | +| hero | `section.page-hero`, `component.hero-dashboard`, `component.metric` | All non-homepage entries in this row carry `hero-candidate`. | +| product | `page.product`, `section.capability-grid`, `section.feature-grid`, `component.feature-item` | All non-page entries in this row carry `product-explainer-candidate`. | +| trust | `page.trust`, `section.trust-grid`, `component.trust-principle-card`, `component.callout` | All supporting entries in this row carry `trust-candidate`. | +| changelog | `page.changelog`, `section.progress-teaser` | Supporting section carries `changelog-candidate`. | +| contact-demo | `page.contact`, `section.cta-section`, `component.contact-panel`, `component.demo-prompt` | Supporting entries in this row carry `contact-candidate`. | +| navigation | `component.navbar` | Canonical navigation surface. | +| footer | `component.footer` | Canonical footer surface. | + +## Reconciliation Notes + +- Pages: 13 entries (`A=5`, `B=5`, `C=1`, `D=2`) +- Sections: 8 entries (`A=7`, `B=0`, `C=1`, `D=0`) +- Components: 30 entries (`A=23`, `B=5`, `C=2`, `D=0`) +- Non-candidates remain visible in the row-level inventory instead of being omitted from the summary. diff --git a/specs/226-astrodeck-inventory-planning/plan.md b/specs/226-astrodeck-inventory-planning/plan.md new file mode 100644 index 00000000..8042cfcf --- /dev/null +++ b/specs/226-astrodeck-inventory-planning/plan.md @@ -0,0 +1,187 @@ +# Implementation Plan: AstroDeck Inventory Planning for Website Rebuild + +**Branch**: `226-astrodeck-inventory-planning` | **Date**: 2026-04-22 | **Spec**: `specs/226-astrodeck-inventory-planning/spec.md` +**Input**: Feature specification from `specs/226-astrodeck-inventory-planning/spec.md` + +**Note**: This template is filled in by the `/speckit.plan` command. See `.specify/scripts/` for helper scripts. + +## Summary + +- Establish a mandatory, repository-referenceable AstroDeck inventory for `apps/website` before any new AstroDeck-based rebuild mapping or task planning. +- Cover all three primitive classes (`Page`, `Section`, `Component`) with unified required attributes, suitability grading, relevance scoring, and risk/candidate markers. +- Keep this feature documentation-only and workspace-local: no runtime route changes, no platform coupling, no new persistence. +- Produce design artifacts (`research.md`, `data-model.md`, `contracts/`, `quickstart.md`) that make follow-up mapping specs (214/215/217 alignment work) deterministic and auditable. + +## Technical Context + +**Language/Version**: Markdown artifacts + Astro 6.0.0 + TypeScript 5.9 context for source discovery +**Primary Dependencies**: Repository spec workflow (`.specify`), Astro website source tree under `apps/website/src`, existing component taxonomy (`primitives`, `content`, `sections`, `layout`) +**Storage**: Filesystem only (`specs/226-astrodeck-inventory-planning/*`) +**Testing**: Documentation quality checks + structural completeness review (no runtime test suite changes) +**Validation Lanes**: N/A (docs-only planning artifact) +**Target Platform**: Monorepo planning workflow with website scope limited to `apps/website` +**Project Type**: Web documentation and planning spec (no executable feature code) +**Performance Goals**: Inventory must be complete enough to avoid ad-hoc primitive selection and support deterministic mapping decisions +**Constraints**: Must remain strictly local to `apps/website`; must capture demo-only and non-candidate primitives; must not pre-commit final mapping choices; must not introduce backend/runtime changes +**Scale/Scope**: Current website primitive landscape spans page entry routes in `apps/website/src/pages`, section composites in `apps/website/src/components/sections`, and component primitives/content/layout in `apps/website/src/components/*` + +## UI / Surface Guardrail Plan + +- **Guardrail scope**: no operator-facing surface change +- **Native vs custom classification summary**: N/A +- **Shared-family relevance**: none +- **State layers in scope**: none +- **Handling modes by drift class or surface**: N/A +- **Repository-signal treatment**: report-only (spec artifacts) +- **Special surface test profiles**: N/A +- **Required tests or manual smoke**: N/A +- **Exception path and spread control**: none +- **Active feature PR close-out entry**: Guardrail + +## Constitution Check + +*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.* + +- Inventory-first: Pass. This feature explicitly enforces inventory-before-mapping as the primary rule. +- Read/write separation: Pass. No write flow, no queue/scheduler, no operational mutation path. +- Graph contract path: N/A. No Microsoft Graph calls. +- Deterministic capabilities: N/A. No capability resolver or runtime authorization semantics added. +- RBAC-UX and workspace/tenant isolation rules: N/A for runtime; this is repository planning documentation only. +- Run observability / Ops-UX: N/A. No `OperationRun` introduced. +- Data minimization: Pass. Only planning metadata; no secrets, no tenant records. +- Test governance (TEST-GOV-001): Pass with docs-only classification and explicit N/A lane decision. +- Proportionality and no premature abstraction: Pass. Adds only a narrow inventory taxonomy needed for immediate follow-up specs. +- Persisted truth and behavioral state: Pass. No DB entity/state machine added. +- UI semantics and layer control: Pass. No new runtime UI semantic framework; taxonomy remains spec-local. +- Filament/operator surface rules: N/A. +- Spec discipline/bloat check: Pass. Taxonomy is scoped to this feature and documented with explicit non-goals. + +Status: ✅ Constitution gate passed for Phase 0. + +## Test Governance Check + +- **Test purpose / classification by changed surface**: N/A (docs-only) +- **Affected validation lanes**: N/A +- **Why this lane mix is the narrowest sufficient proof**: No runtime behavior changes; quality is proven via artifact completeness and reviewable structure. +- **Narrowest proving command(s)**: N/A +- **Fixture / helper / factory / seed / context cost risks**: none +- **Expensive defaults or shared helper growth introduced?**: no +- **Heavy-family additions, promotions, or visibility changes**: none +- **Surface-class relief / special coverage rule**: N/A +- **Closing validation and reviewer handoff**: Reviewers verify required sections, no unresolved clarification markers, and contract/data-model consistency. +- **Budget / baseline / trend follow-up**: none +- **Review-stop questions**: Are all primitive classes covered? Are risks and non-candidates visible? Are follow-up specs able to reference concrete inventory IDs? +- **Escalation path**: document-in-feature +- **Active feature PR close-out entry**: Guardrail +- **Why no dedicated follow-up spec is needed**: This planning unit is itself the prerequisite contract; runtime work comes in later mapping/implementation specs. + +## Project Structure + +### Documentation (this feature) + +```text +specs/226-astrodeck-inventory-planning/ +├── plan.md +├── research.md +├── data-model.md +├── quickstart.md +├── contracts/ +│ └── astrodeck-inventory.logical.openapi.yaml +└── tasks.md +``` + +### Source Code (repository root) + +```text +apps/website/ +├── src/ +│ ├── pages/ # Astro page entrypoints (inventory class: Page) +│ ├── components/ +│ │ ├── sections/ # Composite sections (inventory class: Section) +│ │ ├── primitives/ # Structural primitives (inventory class: Component) +│ │ ├── content/ # Semantic content components (inventory class: Component) +│ │ └── layout/ # Shell/navigation/footer components (inventory class: Component) +│ ├── content/ # Route content definitions used for semantic context +│ ├── styles/ +│ └── types/ +└── tests/ + └── smoke/ +``` + +**Structure Decision**: Keep all implementation planning local to `apps/website` and derive inventory artifacts directly from current page/component directories without introducing a new shared package or backend service. + +## Complexity Tracking + +None. + +## Proportionality Review + +- **Current operator problem**: Rebuild decisions cannot be audited or reproduced when AstroDeck primitive availability is undocumented. +- **Existing structure is insufficient because**: Existing website specs define desired outcomes but not a complete primitive candidate universe. +- **Narrowest correct implementation**: A mandatory inventory contract with required attributes, suitability classes, and candidate/risk markers. +- **Ownership cost created**: Ongoing updates when primitives change; review overhead to keep mappings anchored to inventory references. +- **Alternative intentionally rejected**: Ad-hoc mapping without inventory, because it hides omissions and increases rework risk. +- **Release truth**: Current-release truth. + +*Full BLOAT-001 proportionality review (6 questions) is answered in `specs/226-astrodeck-inventory-planning/spec.md` under "Proportionality Review". The new cross-domain taxonomy (Suitability Class, MarkerVocabulary, Primitive Class, TenantAtlas Relevance) is flagged as "New cross-domain UI framework/taxonomy: yes" with all six BLOAT-001 questions answered there.* + +## Phase 0 — Outline & Research (complete) + +- Output: `specs/226-astrodeck-inventory-planning/research.md` +- Unknowns resolved: + - Concrete primitive discovery boundaries in `apps/website` (`pages`, `sections`, `components` families). + - Practical inventory schema pattern that supports future mapping specs. + - Risk/candidate marker strategy that keeps non-candidates visible. +- Key decisions captured: + - Use repository-derived component taxonomy as inventory source of truth. + - Keep inventory neutral (candidate visibility without premature selection). + - Standardize suitability classes A/B/C/D and relevance levels high/medium/low/none. + - Include demo-only/template-only artifacts explicitly. + +## Phase 1 — Design & Contracts (complete) + +### Data model + +- Output: `specs/226-astrodeck-inventory-planning/data-model.md` +- Defines inventory entities, required attributes, marker vocabulary, and lifecycle/status rules for planning governance. + +### Design contract + +- Output: `specs/226-astrodeck-inventory-planning/contracts/astrodeck-inventory.logical.openapi.yaml` +- Logical contract for inventory ingestion/query/reporting workflows that follow-up mapping specs can consume. + +### Quickstart + +- Output: `specs/226-astrodeck-inventory-planning/quickstart.md` +- Documents the concrete process to generate and validate the inventory from `apps/website` source paths. + +### Agent context update + +- Completed via `.specify/scripts/bash/update-agent-context.sh copilot`. + +### Constitution re-check (post-design) + +- ✅ Still docs-only and workspace-scoped. +- ✅ No runtime mutation, no Graph, no new persistence. +- ✅ Proportionality remains narrow and directly tied to current follow-up mapping needs. +- ✅ No guardrail regressions introduced. + +## Phase 2 — Implementation Plan (next) + +### Story 1 (P1): Build complete primitive inventory + +- Enumerate all relevant Astro page entrypoints, section composites, and component families from `apps/website/src`. +- Capture mandatory fields per entry (identifier, class, role, semantics, visual character, relevance, suitability). +- Ensure demo/template-only entries are included and marked. + +### Story 2 (P1): Add suitability and risk classification + +- Apply A/B/C/D suitability classes and relevance grading to every entry. +- Add marker tags (`tenantatlas-likely`, `visual-risk`, `semantic-risk`, `demo-only`, etc.) where applicable. +- Publish suitability overview and candidate visibility slices for homepage/hero/product/trust/changelog/contact/navigation/footer. + +### Story 3 (P2): Anchor follow-up mappings to inventory + +- Require mapping specs (214/215/217 follow-ups) to reference concrete inventory entry identifiers. +- Document exception path for remove/non-candidate decisions. +- Keep inventory updated as primitives evolve to preserve planning determinism. diff --git a/specs/226-astrodeck-inventory-planning/quickstart.md b/specs/226-astrodeck-inventory-planning/quickstart.md new file mode 100644 index 00000000..8fbfd62f --- /dev/null +++ b/specs/226-astrodeck-inventory-planning/quickstart.md @@ -0,0 +1,114 @@ +# Quickstart: AstroDeck Inventory Planning (Spec 226) + +## Purpose + +Create a complete, mapping-ready AstroDeck inventory for `apps/website` before any rebuild mapping or task re-planning. + +## Preconditions + +- Work from branch `226-astrodeck-inventory-planning`. +- Keep scope strictly inside `apps/website`. +- Do not make final keep/adapt/remove decisions in this step. + +## Step 1: Discover primitive candidates from source paths + +From repository root: + +```bash +cd apps/website +rg --files src/pages src/components/sections src/components/primitives src/components/content src/components/layout +``` + +Classify files into: + +- `Page`: route entrypoints in `src/pages` +- `Section`: composites in `src/components/sections` +- `Component`: reusable units in `src/components/primitives`, `src/components/content`, `src/components/layout` + +## Step 2: Build inventory entries + +For each candidate, capture required attributes (satisfies FR-002 and FR-008): + +- `identifier` +- `primitive_class` +- `file_ref` +- `functional_role` +- `default_semantics` +- `default_visual_character` +- `tenantatlas_relevance` (`high|medium|low|none`) +- `suitability_class` (`A|B|C|D`) + +### Suitability Decision Rubric (FR-008: Bewertungslogik) + +Apply the following criteria consistently across all entries. Consider structure, semantics, rework effort, risk, and reuse potential: + +| Class | Meaning | Typical signals | +|-------|---------|-----------------| +| **A** | Directly reusable as-is for TenantAtlas | Matches enterprise-neutral semantics, no rework needed, no visual/semantic risk | +| **B** | Reusable with minor TenantAtlas adaptation | Needs copy/color/layout tweaks but structural fit is good; low risk | +| **C** | Reusable only with significant rework | Semantic mismatch, heavy visual risk, or complex structural changes required | +| **D** | Not suitable for TenantAtlas use | Wrong domain semantics, demo-only purpose, or fundamentally incompatible design | + +### Marker Application Rules + +Markers are applied per-entry from the allowed `MarkerVocabulary`. Minimum required marker rules: + +- `demo-only` — **required** if the entry has `suitability_class: D` and its purpose is demo/template-only +- `visual-risk` — **required** if `suitability_class` is C and the notes mention visual incompatibility +- `semantic-risk` — **required** if `suitability_class` is C and the notes mention semantic mismatch +- Surface candidate markers (`hero-candidate`, `trust-candidate`, etc.) — **required** if the entry appears in a surface's candidate list in summary.md + +All other markers are optional and additive. + +Add markers where applicable: + +- `tenantatlas-likely` +- `needs-heavy-adaptation` +- `visual-risk` +- `semantic-risk` +- `demo-only` +- `remove-likely` +- `hero-candidate` +- `trust-candidate` +- `navigation-candidate` +- `footer-candidate` +- `contact-candidate` +- `product-explainer-candidate` +- `changelog-candidate` + +## Step 3: Produce summary visibility + +Compute and document: + +- Suitability distribution (`A/B/C/D`) +- Risk visibility counts (`visual-risk`, `semantic-risk`, `demo-only`) +- Candidate visibility for: + - homepage + - hero + - product + - trust + - changelog + - contact/demo + - navigation + - footer + +## Step 4: Validate spec acceptance alignment + +Confirm: + +- All three classes (`Page`, `Section`, `Component`) are present. +- No entry misses required fields. +- Non-candidates are visible, not omitted. +- Inventory remains neutral and does not pre-empt mapping decisions. + +## Step 5: Prepare downstream mapping handoff + +Use stable `entry_id` references for follow-up specs and tasks so mapping choices and exceptions can be traced back to this inventory baseline. + +## Done Criteria + +The quickstart execution is complete when: + +- Inventory artifacts satisfy Spec 226 AC1-AC7. +- Suitability and candidate/risk summaries are present and coherent. +- Follow-up mapping specs can consume inventory IDs without ambiguity. diff --git a/specs/226-astrodeck-inventory-planning/research.md b/specs/226-astrodeck-inventory-planning/research.md new file mode 100644 index 00000000..73dcea5c --- /dev/null +++ b/specs/226-astrodeck-inventory-planning/research.md @@ -0,0 +1,56 @@ +# Research: AstroDeck Inventory Planning for Website Rebuild + +## Decision 1: Inventory source boundaries are directory-driven and explicit + +- **Decision**: Use current `apps/website/src` structure as the mandatory discovery boundary: + - `src/pages` -> `Page` primitives + - `src/components/sections` -> `Section` primitives + - `src/components/primitives`, `src/components/content`, `src/components/layout` -> `Component` primitives +- **Rationale**: This matches how the website is already authored and prevents hidden omissions. +- **Alternatives considered**: + - Inventory only referenced components in current routes: rejected because it misses available but currently unused candidates. + - Inventory from screenshots/manual browsing only: rejected because it is incomplete and non-deterministic. + +## Decision 2: Include demo/template artifacts as first-class inventory entries + +- **Decision**: Mark template/demo artifacts explicitly (e.g., `demo-only`) instead of excluding them. +- **Rationale**: Excluding them early hides available options and weakens auditability of later keep/adapt/remove decisions. +- **Alternatives considered**: + - Exclude demo components from inventory: rejected because it creates selective inventory bias. + +## Decision 3: Suitability classes must be mandatory and exhaustive + +- **Decision**: Every inventory entry receives exactly one suitability class: + - `A` strong candidate + - `B` adaptable candidate + - `C` weak candidate + - `D` non-candidate +- **Rationale**: Follow-up mapping specs require deterministic triage and cannot rely on narrative-only judgments. +- **Alternatives considered**: + - Optional suitability scoring: rejected because it creates inconsistent coverage across entries. + +## Decision 4: Risk and candidate markers are additive, not substitutive + +- **Decision**: Marker tags (e.g., `visual-risk`, `semantic-risk`, `hero-candidate`, `trust-candidate`) augment but do not replace required fields. +- **Rationale**: Tags improve queryability for later mapping while preserving normalized core attributes. +- **Alternatives considered**: + - Use markers only, skip required fields: rejected because it is too ambiguous for cross-spec traceability. + +## Decision 5: Inventory output must be mapping-consumable by contract + +- **Decision**: Define a logical OpenAPI contract for inventory publication and summary retrieval so downstream specs can reference stable structures. +- **Rationale**: A contractized shape increases consistency for future tasks and automation without introducing runtime implementation in this feature. +- **Alternatives considered**: + - Freeform markdown only: rejected because downstream mapping extraction becomes error-prone. + +## Decision 6: Existing repo patterns favor normalized inventories with explicit classes + +- **Decision**: Mirror existing repository planning patterns by using normalized entity fields, explicit classifications, and deterministic summaries. +- **Rationale**: Prior specs (`040`, `042`, `045`) consistently model inventory-like domains with strict fields and taxonomy semantics. +- **Alternatives considered**: + - Introduce a novel inventory schema unrelated to existing specs: rejected because it adds unnecessary cognitive overhead. + +## Resolved Clarifications + +- No unresolved `NEEDS CLARIFICATION` items remain. +- The technical stack and boundaries are sufficient for Phase 1 artifact design. diff --git a/specs/226-astrodeck-inventory-planning/spec.md b/specs/226-astrodeck-inventory-planning/spec.md new file mode 100644 index 00000000..770911bc --- /dev/null +++ b/specs/226-astrodeck-inventory-planning/spec.md @@ -0,0 +1,214 @@ +# 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.)* diff --git a/specs/226-astrodeck-inventory-planning/tasks.md b/specs/226-astrodeck-inventory-planning/tasks.md new file mode 100644 index 00000000..25e45e14 --- /dev/null +++ b/specs/226-astrodeck-inventory-planning/tasks.md @@ -0,0 +1,123 @@ +# Tasks: AstroDeck Inventory Planning for Website Rebuild + +**Input**: Design documents from `specs/226-astrodeck-inventory-planning/` +**Prerequisites**: plan.md ✅ | spec.md ✅ | research.md ✅ | data-model.md ✅ | contracts/ ✅ | quickstart.md ✅ + +**Tests**: N/A — docs-only planning artifact; no runtime behavior changes; quality proven by artifact completeness and structural review. +**Operations**: N/A — no long-running, remote, queued, or scheduled work. +**RBAC**: N/A — no authorization changes. + +--- + +## Phase 1 — Setup + +**Goal**: Initialize inventory folder and catalog metadata header. + +**Independent Test**: `specs/226-astrodeck-inventory-planning/inventory/` directory exists and `catalog.md` is present with all catalog-level fields. + +- [X] T001 Create `specs/226-astrodeck-inventory-planning/inventory/catalog.md` with catalog metadata (`catalog_id`, `scope`, `created_at`, `source_commit`, `status: draft`) per data-model.md InventoryCatalog definition + +--- + +## Phase 2 — Foundational + +**Goal**: Execute primitive discovery to establish the complete source-of-truth file list before any entries are authored. + +**Independent Test**: Discovery command executes cleanly from repo root and every file returned maps to exactly one of the three primitive classes (Page, Section, Component). + +- [X] T002 Run the quickstart discovery command (`rg --files src/pages src/components/sections src/components/primitives src/components/content src/components/layout` from `apps/website`) and record the complete file list in `specs/226-astrodeck-inventory-planning/inventory/catalog.md` under a `## Source Discovery` section with source commit SHA + +--- + +## Phase 3 — User Story 1 (P1): Build Complete Primitive Inventory + +**Story goal**: Complete, class-separated inventory lists for Pages, Sections, and Components — each entry carrying all mandatory fields (FR-001, FR-002, FR-003). + +**Independent Test**: Three inventory files exist; every entry contains `identifier`, `primitive_class`, `file_ref`, `functional_role`, `default_semantics`, `default_visual_character`, `tenantatlas_relevance`, and `suitability_class` without missing fields (SC-001, SC-002). Demo/template-only entries are included (FR-005). + +- [X] T003 [P] [US1] Create `specs/226-astrodeck-inventory-planning/inventory/pages.md` with one entry per Astro page entrypoint (`index`, `product`, `trust`, `changelog`, `contact`, `solutions`, `integrations`, `privacy`, `terms`, `imprint`, `legal`, `security-trust`) using the InventoryEntry schema from `data-model.md`; include `file_ref` pointing to the relevant `apps/website/src/pages/` path; include any additional page files discovered in T002 that are not in the list above + +- [X] T004 [P] [US1] Create `specs/226-astrodeck-inventory-planning/inventory/sections.md` with one entry per section composite (`PageHero`, `FeatureGrid`, `CTASection`, `CapabilityGrid`, `OutcomeSection`, `TrustGrid`, `LogoStrip`, `ProgressTeaser`) and any additional sections discovered in T002; use InventoryEntry schema; include `file_ref` pointing to `apps/website/src/components/sections/` + +- [X] T005 [P] [US1] Create `specs/226-astrodeck-inventory-planning/inventory/components.md` with one entry per component in all three sub-families — primitives (`Button`, `Card`, `Container`, `Grid`, `Stack`, `Section`, `SectionHeader`, `Cluster`, `Badge`, `Input`, `Textarea`), content (`Headline`, `Lead`, `Eyebrow`, `Metric`, `PrimaryCTA`, `SecondaryCTA`, `FeatureItem`, `Callout`, `RichText`, `TrustPrincipleCard`, `DemoPrompt`, `HeroDashboard`, `IntegrationBadge`, `AudienceRow`, `ContactPanel`), and layout (`PageShell`, `Navbar`, `Footer`, `BaseLayout`); group by sub-family under headings `### Primitives`, `### Content`, `### Layout`; use InventoryEntry schema; include `file_ref` pointing to respective `apps/website/src/components/` path + +--- + +## Phase 4 — User Story 2 (P1): Add Suitability and Risk Classification + +**Story goal**: Every inventory entry carries a validated A/B/C/D suitability class, a TenantAtlas relevance level, and all applicable markers from the allowed MarkerVocabulary. Suitability distribution and surface candidate visibility are published in a summary document (FR-004, FR-005, FR-006, FR-007, FR-008). + +**Independent Test**: Every entry in pages, sections, and components files has a non-empty `suitability_class` (A–D) and `tenantatlas_relevance` (high/medium/low/none); no entry is missing markers where applicable; `summary.md` reconciles aggregate counts with row-level entries and covers all 8 required surfaces (SC-003, SC-004). + +- [X] T006 [US2] Apply A/B/C/D suitability classification, TenantAtlas relevance grading, and applicable MarkerVocabulary tags to every entry in `specs/226-astrodeck-inventory-planning/inventory/pages.md`; apply minimum marker rules per quickstart.md (D entries with demo purpose → `demo-only` required; C entries with visual/semantic notes → `visual-risk`/`semantic-risk` required); do not pre-empt mapping decisions + +- [X] T007 [US2] Apply A/B/C/D suitability classification, TenantAtlas relevance grading, and applicable MarkerVocabulary tags to every entry in `specs/226-astrodeck-inventory-planning/inventory/sections.md`; apply minimum marker rules per quickstart.md (C entries with visual/semantic notes → corresponding risk marker required; surface candidate sections → required surface marker); flag risky sections explicitly rather than silently downgrading suitability + +- [X] T008 [US2] Apply A/B/C/D suitability classification, TenantAtlas relevance grading, and applicable MarkerVocabulary tags to every entry in `specs/226-astrodeck-inventory-planning/inventory/components.md`; apply minimum marker rules per quickstart.md (C entries with visual/semantic notes → required risk marker; components appearing in surface candidate list → required surface marker); ensure layout/ sub-family entries use `primitive_class: Component` + +- [X] T009 [US2] Create `specs/226-astrodeck-inventory-planning/inventory/summary.md` containing: suitability distribution table (`count_a`, `count_b`, `count_c`, `count_d`), risk visibility counts (`visual-risk`, `semantic-risk`, `demo-only`), and a surface candidate table covering homepage, hero, product, trust, changelog, contact-demo, navigation, and footer — each surface lists candidate `entry_id` references or an explicit "no direct candidate" note + +--- + +## Phase 5 — User Story 3 (P2): Anchor Follow-up Mapping Specs + +**Story goal**: Downstream mapping specs (214/215/217 alignment work) have a clear reference contract requiring concrete `entry_id` citations. Non-candidate decisions are documented rather than silently omitted (FR-009, FR-010). + +**Independent Test**: `mapping-anchors.md` exists; it includes the mandatory reference rule (no selection without `entry_id`), an example reference block, and an exception path for non-candidate decisions. + +- [X] T010 [US3] Create `specs/226-astrodeck-inventory-planning/inventory/mapping-anchors.md` defining: (1) the mandatory rule that no mapping spec may claim primitive selection without referencing `entry_id` from the active baselined catalog; (2) an example reference block for downstream specs; (3) the exception path for remove/non-candidate decisions that require explicit rationale rather than omission; (4) instructions to refresh the inventory when source primitives change before the next mapping cycle + +--- + +## Final Phase — Polish & Cross-Cutting + +**Goal**: Structural completeness validation, catalog status transition, and agent context update. + +- [X] T011 Cross-validate that all entries in pages, sections, and components files have no missing required fields (SC-002); confirm all entries have `suitability_class` and `tenantatlas_relevance` set (SC-003); confirm all 8 surfaces have a candidate entry or an explicit "no direct candidate" note in `summary.md` (SC-004); record any gaps as inline TODO notes rather than omitting entries; note SC-005 (downstream specs reference inventory) is a forward-governance rule verified in downstream mapping specs, not a done-criterion for Spec 226 + +- [X] T012 Update `specs/226-astrodeck-inventory-planning/inventory/catalog.md` status from `draft` to `reviewed` once T011 passes; add reviewer sign-off section with date and confirmation that suitability summary is reconciled with row-level entries + +- [X] T013 Run `.specify/scripts/bash/update-agent-context.sh copilot` from repo root to record Spec 226 inventory completion in `.github/agents/copilot-instructions.md` + +--- + +## Dependencies + +``` +T001 + └── T002 + ├── T003 (US1, parallel with T004, T005) + ├── T004 (US1, parallel with T003, T005) + └── T005 (US1, parallel with T003, T004) + ├── T006 (US2, depends on T003) + ├── T007 (US2, depends on T004) + └── T008 (US2, depends on T005) + └── T009 (US2, depends on T006+T007+T008) + └── T010 (US3, depends on T009) + └── T011 (Polish, depends on T006+T007+T008+T009+T010) + └── T012 + └── T013 +``` + +**User story completion order**: US1 before US2 (suitability requires populated entries); US2 before US3 (anchoring requires suitability to be visible). + +## Parallel Execution + +Within Phase 3 (US1), T003 + T004 + T005 can be authored simultaneously (different files, no cross-dependency). + +Within Phase 4 (US2), T006 + T007 + T008 can be applied simultaneously (different files) once their respective entry file from US1 is complete. T009 requires all three to be finished. + +## Implementation Strategy + +**MVP scope**: Complete Phase 3 (US1) first — a fully populated entry set with required fields but without suitability is already more useful than no inventory. This allows review and feedback before the classification pass (US2). + +**Incremental delivery**: +1. T001–T002: discovery and catalog header (minutes) +2. T003–T005: three entry files without suitability markers yet (main authoring effort) +3. T006–T009: classification + summary pass +4. T010: mapping anchor contract +5. T011–T013: validation + status transition + context update + +**Total task count**: 13 +**Task count per user story**: US1 → 3 tasks | US2 → 4 tasks | US3 → 1 task | Setup/Foundational → 2 tasks | Polish → 3 tasks +**Parallel opportunities**: Phase 3 (3-way) + Phase 4 initial pass (3-way)