TenantAtlas/specs/408-review-evidence-decision/plan.md

# Implementation Plan: Customer-safe Review, Evidence & Decision Story

**Branch**: `408-review-evidence-decision` | **Date**: 2026-05-28 | **Spec**: [spec.md](spec.md)
**Input**: Feature specification from `/specs/408-review-evidence-decision/spec.md`

## Summary

Deliver one localized public product-story route in `apps/website` that explains Review Packs, Evidence, Accepted Risks, and Decision Summaries, then expose it through existing homepage, platform, use-case, and footer discovery surfaces without changing `apps/platform` or introducing unsupported product claims.

The implementation stays inside the Astro website, reuses the current `siteCopy` content model plus locale-aware routing, and validates the new public route through the existing Playwright smoke suite and static claim scans.

## Technical Context

**Language/Version**: TypeScript 6.0.3 and Astro 6.3.3 content/runtime files  
**Primary Dependencies**: Astro, Playwright, Tailwind CSS v4 (`@tailwindcss/vite`), Starlight docs stack  
**Storage**: N/A (static public website content only)  
**Testing**: Playwright smoke tests in `apps/website/tests/smoke` plus `astro check` during the build script  
**Validation Lanes**: browser, confidence  
**Target Platform**: Static website build and browser-rendered public routes  
**Project Type**: Web application (Astro static site)  
**Performance Goals**: Maintain current public route readability, valid metadata, and no horizontal overflow on desktop/mobile  
**Constraints**: Preserve root workspace contracts (`package.json` scripts, `WEBSITE_PORT`, `apps/*`), keep `apps/platform` untouched, avoid placeholder links, and avoid unsupported portal/export/compliance/provider claims  
**Scale/Scope**: One new German route plus one English route, lightweight homepage/platform/use-case/footer integration, and smoke-test updates

## UI / Surface Guardrail Plan

- **Guardrail scope**: no operator-facing surface change
- **Native vs custom classification summary**: N/A
- **Shared-family relevance**: public website copy, metadata, navigation, footer, and CTA families only
- **State layers in scope**: shell and page
- **Audience modes in scope**: customer/read-only
- **Decision/diagnostic/raw hierarchy plan**: decision-first public marketing copy only; no operator diagnostics or raw evidence surface is introduced
- **Raw/support gating plan**: N/A
- **One-primary-action / duplicate-truth control**: each page surface keeps one primary conversion action to `/contact` and one supporting product-context action to `/platform` or another real route to avoid CTA sprawl
- **Handling modes by drift class or surface**: report-only
- **Repository-signal treatment**: review-mandatory for public claim language and route discoverability
- **Special surface test profiles**: N/A
- **Required tests or manual smoke**: manual-smoke and browser smoke
- **Exception path and spread control**: none
- **Active feature PR close-out entry**: Smoke Coverage

## Shared Pattern & System Fit

- **Cross-cutting feature marker**: yes
- **Systems touched**: `siteCopy` locale dictionaries, homepage composition, platform page composition, use-case page CTAs, footer links, locale helpers, and public route smoke inventory
- **Shared abstractions reused**: `apps/website/src/data_files/site-copy.ts`, `apps/website/src/i18n.ts`, `MainLayout`, `HeroSection`, existing card-grid section patterns, and `apps/website/tests/smoke/smoke-helpers.ts`
- **New abstraction introduced? why?**: none beyond one bounded page component if needed for locale reuse
- **Why the existing abstraction was sufficient or insufficient**: the existing Astro copy-first structure already centralizes public text, locale-aware links, metadata, and smoke coverage; this feature extends those patterns without a new content system or design framework
- **Bounded deviation / spread control**: none

## 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**: Microsoft 365-first and Intune-as-first-strong-domain public wording
- **Platform-core seams**: public governance vocabulary for Review Packs, Evidence, Findings, Accepted Risks, Decision Summaries, customer-safe review content, and follow-up actions
- **Neutral platform terms / contracts preserved**: Review Packs, Evidence, Findings, Accepted Risks, Decision Summary, management review, audit preparation, recovery context, and next action
- **Retained provider-specific semantics and why**: Microsoft 365 and Intune remain explicit to reflect current-release public truth and to avoid generic governance messaging that loses buyer clarity
- **Bounded extraction or follow-up path**: document-in-feature only; any runtime review workspace or export truth stays in later platform specs

## Constitution Check

GATE status before Phase 0 research: Pass for website-only scope.

- Inventory-first: N/A (no inventory/runtime change)
- Read/write separation: Pass (no write behavior)
- Graph contract path: N/A (no Graph/API runtime)
- Deterministic capabilities: N/A
- RBAC-UX and tenant/workspace isolation: N/A (public unauthenticated pages)
- Run observability / OperationRun UX: N/A
- TEST-GOV-001: Pass (browser lane explicit, narrow smoke coverage, no fixture/helper cost expansion planned)
- PROP-001 / ABSTR-001 / PERSIST-001 / STATE-001 / BLOAT-001: Pass (no new persistence, abstractions, enums, or semantic frameworks)
- XCUT-001: Pass (reuse existing site copy, locale helper, CTA, footer, and smoke helper patterns)
- PROV-001: Pass (bounded provider wording, no platform-core runtime coupling)
- DECIDE-AUD-001: N/A for operator/status surfaces; public marketing hierarchy stays copy-only

Post-design re-check after Phase 1: Pass. The research, data model, route contract, and quickstart remain static public-site artifacts only, introduce no runtime truth, and keep `apps/platform` out of scope.

## Test Governance Check

- **Test purpose / classification by changed surface**: Browser
- **Affected validation lanes**: browser, confidence
- **Why this lane mix is the narrowest sufficient proof**: changes are public-route, metadata, CTA, and claim-language concerns best proven by the existing route smoke suite plus build-time Astro checks
- **Narrowest proving command(s)**:
  - `corepack pnpm --filter @tenantatlas/website build`
  - `corepack pnpm --filter @tenantatlas/website test tests/smoke/public-routes.spec.ts`
  - `corepack pnpm --filter @tenantatlas/website test tests/smoke/interaction.spec.ts`
- **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**: public website browser smoke only
- **Closing validation and reviewer handoff**: reviewers verify the new route renders in both locales, discovery links are real, no banned claims appear, and changed files stay within `apps/website` plus feature-spec artifacts
- **Budget / baseline / trend follow-up**: none
- **Review-stop questions**: lane fit, hidden helper cost, overbroad browser assertions, claim-boundary completeness
- **Escalation path**: document-in-feature
- **Active feature PR close-out entry**: Smoke Coverage
- **Why no dedicated follow-up spec is needed**: this is bounded copy/routing work inside existing public-site structures; runtime review-workspace concerns already live in later specs

## Project Structure

### Documentation (this feature)

```text
specs/408-review-evidence-decision/
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── contracts/
│   └── review-pack-story-routes.openapi.yaml
└── spec.md
```

### Source Code (repository root)

```text
apps/website/
├── src/
│   ├── pages/
│   │   ├── platform.astro
│   │   ├── platform/
│   │   │   └── review-packs.astro
│   │   ├── en/
│   │   │   ├── platform.astro
│   │   │   └── platform/
│   │   │       └── review-packs.astro
│   │   ├── use-cases/msp.astro
│   │   ├── use-cases/mittelstand.astro
│   │   ├── en/use-cases/msp.astro
│   │   └── en/use-cases/mittelstand.astro
│   ├── components/
│   │   ├── pages/
│   │   │   ├── HomePage.astro
│   │   │   ├── PlatformPage.astro
│   │   │   └── ReviewPacksPage.astro
│   │   └── sections/landing/HeroSection.astro
│   ├── data_files/site-copy.ts
│   └── i18n.ts
└── tests/smoke/
    ├── public-routes.spec.ts
    ├── interaction.spec.ts
    └── smoke-helpers.ts
```

**Structure Decision**: Web app/Astro structure under `apps/website`; route files stay thin and locale-aware, while one shared `ReviewPacksPage.astro` is the preferred implementation shape for the section-heavy page to avoid German/English markup duplication.

## Route Family Decision

Selected route family: `/platform/...`

Chosen routes:

- `/platform/review-packs`
- `/en/platform/review-packs`

Reasoning:

- The public site already has `/platform` and `/en/platform` product routes.
- Nested `platform` routes already exist in the docs-facing public surface (`/platform/evidence-review/`), so the nested route family is repo-truth and not speculative.
- The route keeps the story attached to the platform narrative without adding another top-level nav family.
- It avoids the weak genericity of `/review-packs` and the collision/confusion risk of `/products/...`, because `/product` and `/products` currently redirect to `/platform`.

Rejected alternatives:

- `/review-packs`: clearer than docs nesting, but weaker IA connection to the product surface.
- `/platform/evidence-reviews`: too close to the existing docs route and weaker on the commercial Review Pack framing.
- `/products/review-packs`: conflicts with current redirect expectations and introduces unnecessary IA ambiguity.

## Discovery Strategy Decision

Selected discovery surfaces:

- Homepage teaser
- Compact platform-page teaser
- MSP use-case crosslink
- Mittelstand / Enterprise IT use-case crosslink
- Footer link

Decision: do not add a main-navigation item by default.

Reasoning:

- The main nav is already dense and optimized for broad category entry points.
- Contextual entry points on homepage, platform, and use-case pages are stronger because they carry the buyer story naturally.
- Footer exposure keeps the route globally reachable without forcing a top-level IA refactor.

## Trust Teaser Decision

Decision: include the trust teaser and point it to `/trust` and `/en/trust`.

Reasoning:

- The route exists today and is already covered in smoke tests.
- The new page needs a real downstream destination for privacy/security/disclosure questions.
- Linking to Trust is safer than inventing a new proof/download destination.

## Static Claim Scan Commands

- `grep -RIn -e 'href="#"' -e 'lorem ipsum' -e 'customer-safe consumption productization' -e 'route-owned' -e 'artifact taxonomy' -e 'source family' -e 'capability registry' -e 'repo-real foundation' -e 'lueckenlose Evidence' -e 'lueckenlose Evidenz' -e 'gerichtsfeste Nachweise' -e 'immutable evidence' -e 'immutable review packs' -e 'complete audit trail' -e 'guarantees audit success' -e 'macht Sie compliant' -e 'DSGVO-konform' -e 'ISO-zertifiziert' -e 'real-time drift' -e 'automatic remediation' -e 'automatic restore' -e 'Google supported' -e 'AWS supported' apps/website/src apps/website/public 2>/dev/null || true`
- `grep -RIn -e 'href="#"' -e 'lorem ipsum' -e 'customer-safe consumption productization' -e 'route-owned' -e 'artifact taxonomy' -e 'source family' -e 'capability registry' -e 'repo-real foundation' -e 'lueckenlose Evidence' -e 'lueckenlose Evidenz' -e 'gerichtsfeste Nachweise' -e 'immutable evidence' -e 'immutable review packs' -e 'complete audit trail' -e 'guarantees audit success' -e 'macht Sie compliant' -e 'DSGVO-konform' -e 'ISO-zertifiziert' -e 'real-time drift' -e 'automatic remediation' -e 'automatic restore' -e 'Google supported' -e 'AWS supported' apps/website/dist 2>/dev/null || true`

## Planned Validation Results Capture

Implementation must record:

- exact website commands run from current `package.json` / `apps/website/package.json`
- static claim scan outcomes
- browser smoke pass/fail notes for desktop and mobile readability
- whether any optional link surface (footer, platform teaser, use-case crosslinks) was intentionally omitted
- confirmation that `apps/platform/**` remained untouched

## Complexity Tracking

No constitutional violations and no bloat-triggering additions are planned for this feature.

## Proportionality Review

N/A for this implementation plan. The feature introduces no new enum/status family, DTO/presenter/envelope layer, persisted entity/table/artifact, interface/contract/registry/resolver, taxonomy system, or cross-domain UI framework. The only new structure is one bounded public page component plus copy entries inside existing website patterns.

## Implementation Close-out

- Discovery surfaces shipped: homepage teaser, platform-page teaser, MSP use-case crosslink, Mittelstand / Enterprise IT use-case crosslink, and footer link.
- Intentionally omitted discovery surface: main-navigation entry. The route remains discoverable through contextual entry points plus the footer without densifying the primary nav.
- `apps/platform/**` scope confirmation: `git diff --name-only -- apps/platform` returned no paths after implementation.

## Validation Log

- `corepack pnpm --filter @tenantatlas/website build`
  - Pass. Astro emitted `/platform/review-packs/index.html` and `/en/platform/review-packs/index.html` into `apps/website/dist`.
- `corepack pnpm --filter @tenantatlas/website test tests/smoke/public-routes.spec.ts tests/smoke/interaction.spec.ts`
  - Pass. `380 passed`, `6 skipped`.
- `grep -RIn ... apps/website/src apps/website/public 2>/dev/null || true`
  - Pass. No matches after claim cleanup.
- `grep -RIn ... apps/website/dist 2>/dev/null || true`
  - Pass. No matches after rebuild.
- `corepack pnpm --filter @tenantatlas/website format:check`
  - Fails on nine pre-existing, untouched files: `src/components/sections/landing/HeroSection.astro`, `src/components/sections/navbar&footer/FooterSection.astro`, `src/components/ui/blocks/IconBlock.astro`, `src/components/ui/blocks/LeftSection.astro`, `src/components/ui/blocks/MainSection.astro`, `src/components/ui/blocks/RightSection.astro`, `src/components/ui/blocks/StatsBig.astro`, `src/components/ui/blocks/StatsSmall.astro`, and `src/components/ui/forms/RegisterModal.astro`.
- `corepack pnpm exec prettier --check <touched-files>`
  - Pass. All modified review-pack implementation files match Prettier style.

## Manual Smoke Notes

Desktop and mobile comprehension checks were run against the rebuilt preview at `http://127.0.0.1:4322` for both `/platform/review-packs` and `/en/platform/review-packs`.

- **SC-001**: Pass. The hero, workflow, review-pack anatomy, and raw-export comparison make it clear within the first visible sections that Tenantial turns Microsoft 365 policy state and drift into Review Packs, Evidence, and decision-ready governance outputs rather than another dashboard or raw export.
- **SC-002**: Pass. MSP value is explicit through the MSP audience card, Service-Review phrasing, Accepted Risk visibility, and the MSP use-case crosslink.
- **SC-003**: Pass. Enterprise IT value is explicit through the enterprise audience card, management-review language, audit-preparation references, and visible recovery-context wording.
- **SC-004**: Pass. Route/metadata/public-link smoke coverage passed for all changed discovery surfaces, and the built HTML placeholder-link assertion stayed green.
- **SC-005**: Pass. Source and dist claim scans returned no banned internal phrases, false compliance/provider claims, or fake export/proof promises after the final copy cleanup.
- **SC-006**: Pass. Desktop and mobile browser checks showed the primary CTA, trust handoff, customer-safe boundary section, and no horizontal overflow or layout breakage on either locale route.