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)

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