TenantAtlas/specs/405-dach-trust-datenschutz-security-website-surface/plan.md

# Implementation Plan: DACH Trust, Datenschutz & Security Website Surface

**Branch**: `405-dach-trust-datenschutz-security-website-surface` | **Date**: 2026-05-25 | **Spec**: `/Users/ahmeddarrazi/Documents/projects/wt-website/specs/405-dach-trust-datenschutz-security-website-surface/spec.md`
**Input**: Feature specification from `/Users/ahmeddarrazi/Documents/projects/wt-website/specs/405-dach-trust-datenschutz-security-website-surface/spec.md`

## Summary

This plan turns Spec 405 into a website-only implementation package for the existing Astro public site. The work refines the current `/trust` and `/en/trust` routes, deepens the trust content model in shared locale copy, links the trust surface from the homepage and footer/navigation touchpoints, and extends the current smoke suite so claim-sensitive wording stays conservative.

The implementation stays inside `apps/website`, reuses the existing public shell, and does not add platform runtime, legal workflow, or backend/API scope.

## Technical Context

**Language/Version**: TypeScript 6, Astro 6, Node.js `>=20.0.0`  
**Primary Dependencies**: Astro, Tailwind CSS v4, Starlight, Playwright  
**Storage**: N/A - static Astro pages and centralized locale copy in TypeScript  
**Testing**: `astro check` via the website build, Playwright smoke tests  
**Validation Lanes**: browser, confidence  
**Target Platform**: static public website rendered for desktop and mobile browsers  
**Project Type**: web application inside the `apps/*` pnpm workspace  
**Performance Goals**: preserve static rendering, no horizontal overflow, readable trust/homepage content on desktop and mobile, and no dependency on JavaScript for primary trust copy visibility  
**Constraints**: `apps/website` only; preserve root scripts, `WEBSITE_PORT`, locale routing, and package names; no false trust/compliance/provider claims; no placeholder links; no fake documents or fake downloads  
**Scale/Scope**: refine one existing trust route plus homepage/footer/navigation/metadata/smoke coverage across German default and English mirrored public routes

## UI / Surface Guardrail Plan

- **Guardrail scope**: public read-only, claim-sensitive website surface plus trust discoverability from homepage/footer/navigation
- **Native vs custom classification summary**: custom Astro public pages on shared public layout primitives
- **Shared-family relevance**: public navigation, footer, metadata, and contact handoff
- **State layers in scope**: page, route, metadata
- **Audience modes in scope**: customer/read-only
- **Decision/diagnostic/raw hierarchy plan**: buyer-facing summary first, requestable/legal-readiness detail second, no raw provider/support evidence on the public page
- **Raw/support gating plan**: raw support detail is omitted from the public site and handed off only through a real contact path when needed
- **One-primary-action / duplicate-truth control**: the trust page is the canonical detailed trust surface; homepage and footer only tease or route toward it
- **Handling modes by drift class or surface**: report-only public content surface; any verified hard claim becomes review-mandatory before merge
- **Repository-signal treatment**: forbidden-claim matches, placeholder links, and fake document destinations are review-mandatory failures
- **Special surface test profiles**: N/A - public website smoke only
- **Required tests or manual smoke**: static claim scan, website build, public route smoke, desktop/mobile readability checks
- **Exception path and spread control**: none; any trust statement that needs backend proof, runtime state, or legal workflow is split to a follow-up spec
- **Active feature PR close-out entry**: Smoke Coverage

## Shared Pattern & System Fit

- **Cross-cutting feature marker**: yes
- **Systems touched**: `apps/website/src/components/pages/TrustPage.astro`, `HomePage.astro`, `apps/website/src/data_files/site-copy.ts`, public navigation/footer wiring, and `apps/website/tests/smoke/*`
- **Shared abstractions reused**: `MainLayout.astro`, `siteCopy`, `localizeHref`, the public navbar/footer shell, and the Playwright smoke helpers
- **New abstraction introduced? why?**: none
- **Why the existing abstraction was sufficient or insufficient**: the existing public shell, locale copy source, and smoke suite are sufficient for route, copy, and validation behavior; only the trust route depth is insufficient today
- **Bounded deviation / spread control**: the trust page may add page-local sections or lightweight presentation helpers, but no new content framework, CMS layer, or cross-page trust abstraction is introduced

## 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
- **Provider-owned seams**: public wording for Microsoft Graph permissions and Microsoft-specific provider access examples
- **Platform-core seams**: provider-neutral terms such as provider, capability, permission posture, governance evidence, audit context, retention, and support access
- **Neutral platform terms / contracts preserved**: provider, capability, governance evidence, auditability, recovery context, trust topic, claim status
- **Retained provider-specific semantics and why**: Microsoft Graph remains the explicit example because Microsoft 365 is the current public market and the trust page must explain that first-provider reality honestly
- **Bounded extraction or follow-up path**: follow-up-spec for detailed provider permission matrices, public provider taxonomy, and automated claim guardrails

## Constitution Check

**Pre-Phase 0 gate result**: PASS

- **Inventory-first / snapshots / Graph contract path / deterministic capabilities**: N/A - no product runtime, Graph access, or platform state is changed.
- **Read/write separation / OperationRun / audit logging / automation / RBAC / workspace isolation / tenant isolation**: N/A - public static website only.
- **Shared pattern first (XCUT-001)**: PASS - reuses the existing Astro public shell, locale copy source, navbar/footer, and smoke helpers.
- **Provider boundary (PROV-001)**: PASS - Microsoft-specific permission wording stays bounded to provider-specific explanatory text while the main trust model stays provider-neutral.
- **UI semantics / few layers / V1 explicitness (UI-SEM-001, LAYER-001, V1-EXP-001)**: PASS - no presenter framework, no CMS layer, and no persisted semantics are introduced; the plan extends page-local copy and route structure directly.
- **Proportionality / no premature abstraction / persisted truth / state discipline / bloat check (PROP-001, ABSTR-001, PERSIST-001, STATE-001, BLOAT-001)**: PASS - the only new semantic element is a bounded public claim-status vocabulary, justified by the public false-assurance risk and kept out of persistence/runtime layers.
- **Test governance (TEST-GOV-001)**: PASS - browser/confidence lanes are the narrowest sufficient proof; no new heavy family or backend lane is introduced.
- **Hard stop condition**: any implementation that wants to publish a verified hosting, compliance, certification, or zero-data claim must provide current proof or downgrade the wording before merge.

**Post-Phase 1 gate result**: PASS

- The design artifacts stay within the existing Astro website.
- Contracts describe observable public routes only; no backend API or runtime coupling is introduced.
- Data modeling remains conceptual/editorial only and introduces no persisted entities, provider runtime seams, or legal workflow machinery.

## Test Governance Check

- **Test purpose / classification by changed surface**: Browser
- **Affected validation lanes**: browser, confidence
- **Why this lane mix is the narrowest sufficient proof**: the feature changes public HTML routes, localized copy, metadata, and CTA/link behavior; the existing website build plus public-route smoke coverage exercises the real user surface directly
- **Narrowest proving command(s)**:
  - `corepack pnpm build:website`
  - `corepack pnpm --filter @tenantatlas/website test`
  - targeted static `rg` scan for forbidden trust claims and placeholder links
- **Fixture / helper / factory / seed / context cost risks**: minimal; only existing Playwright helpers and route metadata may grow
- **Expensive defaults or shared helper growth introduced?**: no - smoke helper growth remains route/content assertions only
- **Heavy-family additions, promotions, or visibility changes**: none
- **Surface-class relief / special coverage rule**: N/A - public website smoke only
- **Closing validation and reviewer handoff**: reviewers should rerun the website build, the website Playwright suite, and the forbidden-claim scan; verify that `/trust` and `/en/trust` are reachable from homepage/footer/nav, that primary trust copy remains visible without JavaScript, and that no hard trust claim appears without documented verification
- **Budget / baseline / trend follow-up**: none expected
- **Review-stop questions**: lane fit, hidden claim logic in copy helpers, accidental placeholder links, and any attempt to expand into backend/legal workflow scope
- **Escalation path**: follow-up-spec if implementation needs runtime truth, legal workflow, or a broader content framework
- **Active feature PR close-out entry**: Smoke Coverage
- **Why no dedicated follow-up spec is needed**: the validation stays inside the existing static website build and smoke suite unless recurring trust-page complexity or claim-guardrail drift forces structural automation later
- **Close-out recording requirement**: the implementation close-out must either confirm that no deferred follow-up specs were created or list the required follow-up spec IDs, and any retained hard trust claim must be documented in PR notes with its exact text, verification source, and publication rationale

## Project Structure

### Documentation (this feature)

```text
specs/405-dach-trust-datenschutz-security-website-surface/
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── contracts/
│   └── public-trust-routes.openapi.yaml
└── tasks.md
```

### Source Code (repository root)

```text
apps/website/
├── src/
│   ├── components/
│   │   ├── pages/
│   │   │   ├── HomePage.astro
│   │   │   └── TrustPage.astro
│   │   ├── sections/
│   │   │   └── navbar&footer/
│   │   └── ui/
│   ├── data_files/
│   │   └── site-copy.ts
│   ├── layouts/
│   │   └── MainLayout.astro
│   ├── pages/
│   │   ├── index.astro
│   │   ├── trust.astro
│   │   └── contact.astro
│   ├── i18n.ts
│   └── utils/
│       └── navigation.ts
├── tests/
│   └── smoke/
│       ├── interaction.spec.ts
│       ├── public-routes.spec.ts
│       └── smoke-helpers.ts
└── package.json
```

**Structure Decision**: keep the implementation inside the existing Astro website and its smoke suite. No new package, backend, docs app, or platform integration layer is introduced.

## Complexity Tracking

| Violation | Why Needed | Simpler Alternative Rejected Because |
|-----------|------------|-------------------------------------|
| none | N/A | N/A |

## Proportionality Review

- **Current operator problem**: public evaluators cannot distinguish verified trust facts from request-based, planned, or intentionally unclaimed items, which increases false-assurance risk and slows DACH evaluation.
- **Existing structure is insufficient because**: the current trust route is too shallow and does not expose the required trust topics or an explicit current-vs-planned status language.
- **Narrowest correct implementation**: extend the current `TrustPage.astro` and localized copy model with page-local sections, a six-state claim-status vocabulary, and smoke assertions on real public routes.
- **Ownership cost created**: maintain localized trust copy, a small set of claim-status assertions, and verification notes for any future hard trust claims.
- **Alternative intentionally rejected**: a separate trust CMS, downloadable trust center, or legal-workflow backend, because those would add unsupported scope and unverified artifacts.
- **Release truth**: current-release public website truth only, with follow-up specs carrying any future procurement, public docs, or automation depth.

## Phase 0: Research Output

Phase 0 resolves the implementation-shape questions without introducing code:

- confirm whether the existing route stays `/trust` or changes to a German alias
- confirm the existing content source and locale strategy
- confirm the real CTA/request handoff for trust documents and security questions
- confirm the narrowest route/metadata/smoke contract
- confirm how to represent the public route surface contract without inventing a backend API

The output is [`research.md`](/Users/ahmeddarrazi/Documents/projects/wt-website/specs/405-dach-trust-datenschutz-security-website-surface/research.md), and it removes all planning uncertainty for this feature.

## Phase 1: Design & Contracts

Phase 1 produces the non-code design package that a later implementation can follow directly:

- [`data-model.md`](/Users/ahmeddarrazi/Documents/projects/wt-website/specs/405-dach-trust-datenschutz-security-website-surface/data-model.md) for the editorial content model
- [`contracts/public-trust-routes.openapi.yaml`](/Users/ahmeddarrazi/Documents/projects/wt-website/specs/405-dach-trust-datenschutz-security-website-surface/contracts/public-trust-routes.openapi.yaml) for the observable public HTTP surface
- [`quickstart.md`](/Users/ahmeddarrazi/Documents/projects/wt-website/specs/405-dach-trust-datenschutz-security-website-surface/quickstart.md) for implementation and validation steps

The design stays route- and content-focused. It does not create runtime entities, backend endpoints, or platform ownership changes.

## Phase 2: Implementation Strategy Preview

The planned implementation sequence is:

1. update localized trust/homepage/footer metadata copy in `apps/website/src/data_files/site-copy.ts`
2. expand `apps/website/src/components/pages/TrustPage.astro` into the canonical trust surface
3. tighten the homepage trust teaser and any trust-discoverability touchpoints in `HomePage.astro` and shared navbar/footer inputs if needed
4. extend `apps/website/tests/smoke/public-routes.spec.ts`, `interaction.spec.ts`, and `smoke-helpers.ts` for trust-route assertions and forbidden-claim coverage
5. validate with website build, smoke tests, and static scans only

Explicitly out of scope during implementation:

- `apps/platform`
- dependency changes
- runtime form submission/backend work
- downloadable legal packs or fake document links
- provider-permission runtime matrices
- verified compliance/certification/hosting claims without source proof