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 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)

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)

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.