ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
94cff6ca03
TenantAtlas/specs/406-provider-policy-domain-public-taxonomy/plan.md
ahmido 09dc9988cb 406: Provider & Policy Domain Public Taxonomy (#401) 
## Summary
- add the 406 feature specification for a public provider and policy-domain taxonomy surface
- include plan, research, data model, quickstart, checklist, and public route contract artifacts
- update agent context with the 406 website technology notes

## Notes
- this PR is spec and planning work only
- no runtime website implementation is included yet

## Validation
- reviewed pending git scope before commit
- verified `Agents.md` has no editor diagnostics

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #401
2026-05-26 12:54:23 +00:00

185 lines
14 KiB
Markdown
Raw Blame History

# 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](/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)
```text
/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)
```text
/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](/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/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/contracts/public-taxonomy-routes.openapi.yaml)
- [/Users/ahmeddarrazi/Documents/projects/wt-website/specs/406-provider-policy-domain-public-taxonomy/quickstart.md](/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.
Reference in New Issue View Git Blame Copy Permalink