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

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)

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)

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.