TenantAtlas/specs/406-provider-policy-domain-public-taxonomy/plan.md

Implementation Plan: Provider & Policy Domain Public Taxonomy

Branch: 406-provider-policy-domain-public-taxonomy | Date: 2026-05-26 | Spec: /Users/ahmeddarrazi/Documents/projects/wt-website/specs/406-provider-policy-domain-public-taxonomy/spec.md
Input: Feature specification from /Users/ahmeddarrazi/Documents/projects/wt-website/specs/406-provider-policy-domain-public-taxonomy/spec.md

Summary

Create a website-only public taxonomy surface that explains Tenantial's provider and policy-domain posture: Microsoft 365 first, Intune as the first strong policy focus, adjacent Microsoft 365 domains safely labeled by status, and Google/AWS/Okta framed only as future architecture direction unless verified. The implementation approach is to add a localized Astro public route at /platform/domains and /en/platform/domains, reuse the existing public website shell, content data, CTA, navigation, footer, metadata, and Playwright smoke-test patterns, and keep all platform runtime files untouched.

Technical Context

Language/Version: TypeScript 6.0.3, Astro 6.3.3, Tailwind CSS 4.3.0
Primary Dependencies: Astro, @astrojs/check, @astrojs/sitemap, Tailwind CSS v4, Playwright smoke tests
Storage: N/A - static public website content only; no runtime persistence
Testing: corepack pnpm --filter @tenantatlas/website build and corepack pnpm --filter @tenantatlas/website test; optional format:check if formatting scope is touched
Validation Lanes: confidence, browser
Target Platform: static public website built from /Users/ahmeddarrazi/Documents/projects/wt-website/apps/website, local preview on WEBSITE_PORT with default 4321
Project Type: web application, website package only
Performance Goals: taxonomy page should be statically generated; first-time evaluators can identify Microsoft 365 first and Intune as one domain within 60 seconds; desktop and mobile layouts must avoid horizontal overflow
Constraints: apps/website only; no apps/platform; no root script contract changes; preserve package name @tenantatlas/website; preserve WEBSITE_PORT; no fake logos, badges, placeholder links, or unsupported provider claims
Scale/Scope: one localized taxonomy route pair, light homepage/platform/nav/footer integration, public metadata updates, static claim scans, and website smoke coverage

UI / Surface Guardrail Plan

• Guardrail scope: no authenticated operator-facing surface change; public website claim-guardrail surface only
• Native vs custom classification summary: existing Astro public website primitives and Tailwind conventions; no Filament/admin UI
• Shared-family relevance: public navigation, footer links, CTA links, public metadata, public status labels
• State layers in scope: page content, route, metadata, navigation/footer copy; no runtime state
• Audience modes in scope: public buyer/evaluator only; no operator-MSP/support-platform modes
• Decision/diagnostic/raw hierarchy plan: buyer-facing explanation only; no diagnostics or raw evidence
• Raw/support gating plan: N/A - no raw/support evidence exposed
• One-primary-action / duplicate-truth control: route should expose one main CTA back to real contact or platform context; homepage/platform teasers stay short and link to the taxonomy rather than restating it
• Handling modes by drift class or surface: report-only website claim guardrail; unsupported provider claims are implementation blockers for this feature
• Repository-signal treatment: review-mandatory for risky public claims and placeholder links found by static scans
• Special surface test profiles: N/A - public website surface
• Required tests or manual smoke: website build, Playwright public-route smoke, desktop/mobile browser smoke if preview is available, static risky-claim scan
• Exception path and spread control: none; any runtime provider support or public roadmap governance must move to a follow-up spec
• Active feature PR close-out entry: Smoke Coverage

Shared Pattern & System Fit

• Cross-cutting feature marker: yes
• Systems touched: /Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/src/pages, /Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/src/components/pages, /Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/src/data_files/site-copy.ts, /Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/src/utils/navigation.ts, public route smoke tests
• Shared abstractions reused: MainLayout, existing page-component pattern, siteCopy, localizeHref, localizedPath, current navbar/footer content conventions, existing Playwright smoke helpers
• New abstraction introduced? why?: none; use page-local content objects and existing component conventions
• Why the existing abstraction was sufficient or insufficient: the website already renders localized public pages from shared copy and layout primitives; the taxonomy needs content and route extension, not a new content framework
• Bounded deviation / spread control: dedicated /platform/domains route is a bounded IA addition; it must not become a runtime provider roadmap framework

OperationRun UX Impact

• Touches OperationRun start/completion/link UX?: no
• Central contract reused: N/A
• Delegated UX behaviors: N/A
• Surface-owned behavior kept local: none
• Queued DB-notification policy: N/A
• Terminal notification path: N/A
• Exception path: none

Provider Boundary & Portability Fit

• Shared provider/platform boundary touched?: yes, public vocabulary only
• Provider-owned seams: Microsoft 365, Intune, Entra, Conditional Access, SharePoint/OneDrive, Enterprise Apps, Service Principals as public examples and Microsoft-specific domains
• Platform-core seams: public neutral terms such as provider, managed environment, provider connection, policy domain, policy evidence, governance review, audit trail, controlled recovery, review pack, claim boundary
• Neutral platform terms / contracts preserved: provider, provider connection, managed environment, policy domain, policy evidence, review pack, audit trail
• Retained provider-specific semantics and why: Microsoft 365 and Intune stay explicit because they are current public market positioning; non-Microsoft providers stay future architecture direction unless verified
• Bounded extraction or follow-up path: document-in-feature for route/IA decision; follow-up-spec for runtime provider support, detailed provider capability documentation, or public roadmap governance

Constitution Check

Pre-Design Gate

• Inventory-first / snapshots-second: Pass. No inventory, snapshots, backups, or external tenant state changes.
• Read/write separation: Pass. Public website content only; no tenant or provider writes.
• Graph contract path: Pass. No Microsoft Graph calls or contract registry changes.
• Deterministic capabilities: Pass. No runtime capability derivation changes.
• RBAC / workspace / tenant isolation: Pass. Public read-only website; no authenticated routes, memberships, or capability enforcement changes.
• Run observability / OperationRun: Pass. No queued, remote, scheduled, long-running, or OperationRun-linked work.
• Automation and data minimization: Pass. No automation, logs, secrets, or provider data.
• Test governance: Pass with website Browser/confidence lane; no platform fixtures or heavy governance suite expansion.
• Proportionality / bloat: Pass with bounded website-only taxonomy/status vocabulary; no persisted state, runtime enum, provider registry, or abstraction.
• Provider boundary: Pass. Public vocabulary separates Microsoft current focus from future-provider architecture direction and avoids live claims.
• Shared pattern first: Pass. Reuse existing website layout/copy/navigation/test patterns.
• Filament/admin UI checks: N/A. No Laravel, Filament, Livewire, or admin/operator surface changes.

Gate Result: PASS. No unjustified constitution violations.

Test Governance Check

• Test purpose / classification by changed surface: Browser for public website route/content; confidence for static build and type/content checks
• Affected validation lanes: confidence, browser
• Why this lane mix is the narrowest sufficient proof: the feature is a public static website surface; build/check proves static generation and Playwright smoke proves route reachability, metadata, links, mobile/desktop readability, and claim visibility
• Narrowest proving command(s): corepack pnpm --filter @tenantatlas/website build; corepack pnpm --filter @tenantatlas/website test; static grep/rg claim scan across /Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/src and /Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/public
• 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 - public website surface
• Closing validation and reviewer handoff: reviewers should confirm apps/platform is untouched, all exposed links are real, status labels are visible, non-Microsoft providers are not live claims, and smoke tests cover German and English taxonomy routes
• Budget / baseline / trend follow-up: none expected
• Review-stop questions: stop if route links are placeholders, copy claims unsupported provider availability, generated output contains risky claims, or implementation touches platform runtime
• Escalation path: follow-up-spec only for runtime provider support or public roadmap governance
• Active feature PR close-out entry: Smoke Coverage
• Why no dedicated follow-up spec is needed: the planned change is one bounded public website taxonomy; routine test and content upkeep stays inside this feature

Project Structure

Documentation (this feature)

/Users/ahmeddarrazi/Documents/projects/wt-website/specs/406-provider-policy-domain-public-taxonomy/
|-- plan.md
|-- research.md
|-- data-model.md
|-- quickstart.md
|-- contracts/
|   `-- public-taxonomy-routes.openapi.yaml
`-- tasks.md

Source Code (repository root)

/Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/
|-- package.json
|-- src/
|   |-- components/
|   |   `-- pages/
|   |       |-- DomainTaxonomyPage.astro
|   |       |-- HomePage.astro
|   |       `-- PlatformPage.astro
|   |-- data_files/
|   |   `-- site-copy.ts
|   |-- pages/
|   |   |-- platform/
|   |   |   `-- domains.astro
|   |   `-- en/
|   |       `-- platform/
|   |           `-- domains.astro
|   `-- utils/
|       `-- navigation.ts
`-- tests/
    `-- smoke/
        |-- public-routes.spec.ts
        |-- interaction.spec.ts
        `-- smoke-helpers.ts

Structure Decision: Use the existing Astro website structure under /Users/ahmeddarrazi/Documents/projects/wt-website/apps/website. Add a localized page component and nested static routes for /platform/domains and /en/platform/domains; update existing copy/navigation/tests rather than introducing a new content system.

Complexity Tracking

Violation	Why Needed	Simpler Alternative Rejected Because
None	N/A	N/A

Proportionality Review

• Current operator problem: public evaluators cannot tell which domains are current focus, planned, future direction, unavailable, or not claimed
• Existing structure is insufficient because: homepage/platform prose alone cannot distinguish Microsoft 365 first, Intune as one domain, adjacent Microsoft domains, and future non-Microsoft providers without either narrowing or overclaiming
• Narrowest correct implementation: one website-only taxonomy route pair with page-local status labels and claim boundaries, plus light discoverability
• Ownership cost created: future website copy and tests must keep statuses, metadata, and provider claims aligned with product truth
• Alternative intentionally rejected: runtime provider capability registry, CMS, or public roadmap framework; those would add machinery beyond the current public-claim problem
• Release truth: current public website truth with bounded future-provider direction language

Phase 0: Research

Research tasks were derived from route, localization, validation, and provider-claim unknowns. Findings are consolidated in /Users/ahmeddarrazi/Documents/projects/wt-website/specs/406-provider-policy-domain-public-taxonomy/research.md. No NEEDS CLARIFICATION items remain.

Phase 1: Design And Contracts

Design artifacts are:

• /Users/ahmeddarrazi/Documents/projects/wt-website/specs/406-provider-policy-domain-public-taxonomy/data-model.md
• /Users/ahmeddarrazi/Documents/projects/wt-website/specs/406-provider-policy-domain-public-taxonomy/contracts/public-taxonomy-routes.openapi.yaml
• /Users/ahmeddarrazi/Documents/projects/wt-website/specs/406-provider-policy-domain-public-taxonomy/quickstart.md

Post-Design Constitution Check

• Gate Result: PASS.
• Reason: Phase 1 keeps the taxonomy website-only, static, and page-local. It introduces no persistence, runtime provider support, platform capability registry, Graph calls, RBAC changes, OperationRun behavior, Filament surfaces, or root workspace script changes.
• Remaining review focus: ensure implementation does not turn status labels into runtime state, does not publish unsupported provider availability, does not add fake provider logos/badges, and does not touch /Users/ahmeddarrazi/Documents/projects/wt-website/apps/platform.

Phase 2: Planning Boundary

This /speckit.plan output stops before task generation. /speckit.tasks should create implementation tasks from this plan, the spec, and the generated design artifacts.