docs: add approved portfolio design and plans

docs/reviews/2026-09-01-portfolio-spec-independent-review.md

@@ -0,0 +1,225 @@
+# Independent Review — Portfolio Journey Design Specification
+
+**Date:** 2026-09-01  
+**Reviewed artifact:** `2026-09-01-portfolio-journey-design.md`  
+**Review method:** Four independent, isolated reviewers with no conversation context and no file-edit permission
+
+## Review scopes
+
+1. Architecture, correctness, product coherence, and implementation feasibility
+2. Security, privacy, media handling, supply chain, and deployment controls
+3. Performance, resilience, lifecycle behavior, and testability
+4. Specification quality, audience fit, accessibility, SEO, and content credibility
+
+## Overall verdict
+
+**Review closed — approved for implementation planning.**
+
+No reviewer found a critical conceptual flaw. The original review identified implementation-contract gaps rather than problems with the moving-road concept, car, section signs, restrained content layer, optional audio, no-public-CV decision, or private-project naming policy. Those gaps were remediated through Revision 8 and targeted confirmation passes. Architecture returned a clean Critical/High pass. The remaining High security and performance findings were resolved directly in the final revision, after which the review loop was deliberately closed as disproportionate to a design document.
+
+## Review closure
+
+- Architecture: clean independent Critical/High confirmation pass.
+- Security: final High findings addressed by independent dual-worker/matcher validation, explicit policy/tool-provenance issuer recovery, exact attestation binding, trusted-time expiry checks, and atomic public visibility.
+- Performance and correctness: final High findings addressed by non-overlapping physical actions, terminal-Static branching, deterministic navigation-cancellation barriers, and an exact `maxScrollY` oracle.
+- Accessibility, SEO, content credibility, and audience fit: incorporated from the original independent review into the final acceptance gates.
+- No implementation code was started during review.
+
+The detailed findings below are retained as the historical audit trail; they no longer describe the current specification's status.
+
+## Consensus strengths
+
+- Essential content is independent of WebGL, audio, hydration, and JavaScript failure.
+- Native scrolling, real anchors, and the absence of a router are appropriate for the document.
+- The project descriptions avoid fake metrics and honestly label private, modest, experimental, and work-in-progress projects.
+- The specification treats keyboard use, reduced motion, static fallback, mobile layouts, and screen readers as first-class concerns.
+- The privacy policy already covers visible copy, alt text, filenames, metadata, source maps, structured data, and private links.
+- Scene, semantic content, coordination, and audio responsibilities are separated cleanly.
+- SEO direction correctly prioritizes complete HTML, a canonical identity, crawlable links, and verified profiles rather than promising a ranking.
+
+## Required revisions
+
+### 1. Define the exact static-generation contract
+
+The current combination of Vue, Vite, pre-rendering, and hydration does not name the mechanism that produces complete HTML.
+
+The revised specification should:
+
+- choose the exact static-generation or pre-render implementation;
+- define a typed build-time `siteConfig` containing canonical URL, email, optional verified social profiles, production environment, and metadata;
+- fail the production build when required values are missing or invalid;
+- describe how HTML, JSON-LD, sitemap, robots directives, and hydration are generated;
+- clarify that production artifacts are host-specific even though the application remains portable across static hosts;
+- rename the product architecture to “a pre-rendered single-page document with progressive Vue enhancement,” avoiding the client-shell implications of “SPA.”
+
+### 2. Replace screenshot redaction with a closed asset-clearance pipeline
+
+Removing private product names is insufficient for medication and healthcare media. Screenshots may expose names, emails, medication information, notifications, URLs, tokens, hostnames, QR codes, or environment details. Other footage may raise ownership or public-display concerns.
+
+Every published asset should have a clearance record containing:
+
+- safe public asset ID and generated output filename;
+- source, owner, license or permission, attribution requirement, and public-display rights;
+- privacy classification and approval owner;
+- confirmation that health-related interfaces use synthetic/demo data only;
+- OCR and full-resolution manual review results;
+- video frame-review and container-track results;
+- metadata-stripping and safe-format transcoding results;
+- sanitized output hash and final approval.
+
+Private identifiers should be pseudonymized before content enters a public repository. Privacy gates must run before preview deployment as well as production. Seeded canary tests should prove the gate catches identifiers in HTML, filenames, source maps, metadata, images, and video.
+
+### 3. Create an authoritative content and evidence register
+
+The specification requires factual CV copy and honest project descriptions but does not define the source revision, approved copy, evidence, or verification owner.
+
+The content model should record, for every role and project:
+
+- approved title and bounded copy;
+- source and as-of date;
+- Luca’s role and contribution;
+- problem, technical decisions, outcome, and maturity state;
+- verified public URL or an explicit private/no-link state;
+- approved asset IDs and accessibility descriptions;
+- factual, licensing, and privacy approval.
+
+Experience should be reverse chronological with one consistent date and location format. The on-page profile should define the verified hiring-screening facts that remain public because a CV download is intentionally unavailable.
+
+### 4. Balance systems and software evidence
+
+The stated identity is an equal hybrid, but the current content allocation can read as “developer with a homelab.”
+
+Infrastructure should receive comparable narrative and visual weight through verified evidence of:
+
+- reverse proxy and certificate lifecycle;
+- authentication and access-policy design;
+- service deployment, updates, enrollment, and retirement;
+- failure investigation or incident-style debugging;
+- backup/recovery, monitoring, automation, or hardening where facts are available.
+
+This should not become a full service inventory or disclose operationally sensitive details. The final diagram must exclude real hostnames, addresses, ports, versions, usernames, recovery endpoints, and exact security rules.
+
+### 5. Define one deterministic journey/navigation state machine
+
+Intersection observers, measured positions, fragments, history, focus, and browser restoration currently have no authority or precedence rules.
+
+The revised specification should define:
+
+- a single active-section algorithm and boundary line;
+- tie-breaking for tall, short, and overlapping sections;
+- recalculation after font load, media load, resize, and orientation change;
+- explicit navigation using one history entry, passive scroll using no new entry or `replaceState`, and `popstate` never pushing;
+- direct-fragment and bfcache restoration behavior;
+- loop suppression between scrolling, URL updates, and focus;
+- a strict rule that scrolling and observers never move keyboard or screen-reader focus;
+- focus behavior for keyboard activation, pointer activation, direct fragments, and back/forward navigation.
+
+Sign, HUD, navigation, environment chapter, and semantic section IDs should agree within one animation frame.
+
+### 6. Add explicit WebGL and Web Audio lifecycle models
+
+Asynchronous scene and audio initialization can otherwise create duplicate contexts, late attachments, leaked resources, or misleading controls.
+
+The scene needs named states such as `idle`, `loading`, `running`, `paused`, `lost`, `static`, and `disposed`, with an abort/generation guard for every asynchronous completion. Teardown must cancel animation frames, listeners, observers, loaders, geometries, materials, textures, render targets, and post-processing exactly once.
+
+On WebGL context loss, rendering stops immediately. One restoration event may rebuild resources; failure within a fixed timeout or any later context loss forces static mode for the session.
+
+Audio remains an approved feature, but it is non-blocking. It needs idempotent `idle`, `starting`, `running`, `suspended`, `interrupted`, `failed`, and `closed` states. Rapid activation must create one context and one graph. Rejected starts show a quiet “audio unavailable” state. Visibility, mobile interruption, bfcache, mute-during-startup, and teardown behavior must be explicit.
+
+### 7. Make reduced-motion and adaptive-quality precedence exact
+
+System reduced motion and manual pause always force static behavior. A saved full-motion preference never silently overrides a current system preference.
+
+When reduced motion is known at initial load, Three.js and animated project media are not downloaded or initialized. A runtime transition to static cancels rendering and decorative media promptly while leaving audio independently controllable.
+
+Adaptive quality needs numerical frame-time thresholds, a sampling window, hysteresis, and precedence rules. User-selected quality is a maximum tier; the controller may downgrade but does not automatically upgrade during the session. Repeated context failure and reduced motion always override the selected tier.
+
+### 8. Separate reproducible lab gates from field performance goals
+
+Core Web Vitals p75 values are field metrics and cannot be proven from an undefined “production-like” test, especially when the initial release intentionally has no analytics.
+
+The revised specification should:
+
+- define exact cold-cache lab devices, browsers, network and CPU throttling, run count, tool, and aggregation method;
+- set compressed byte budgets for critical HTML/CSS, initial Vue JavaScript, poster, fonts, scene chunk/assets, and video;
+- cap mobile DPR, texture dimensions, GPU assets, post-initialization long tasks, and per-tier scene frame time;
+- define downgrade thresholds and cooldown;
+- treat LCP, INP, and CLS p75 as post-launch goals unless a separately privacy-reviewed, minimal RUM design is approved;
+- keep the initial release free of analytics SDKs, tracking pixels, cookies, device fingerprinting, and telemetry endpoints.
+
+### 9. Strengthen media and accessibility behavior
+
+- Quantitative chart groups need visible captions and adjacent structured descriptions covering purpose, axes, variables, key trends, and conclusions; use a data table when exact values matter.
+- Automatically moving media longer than five seconds needs a visible, keyboard-operable pause control.
+- Reduced-motion and data-saver modes use posters until explicit play.
+- Media uses `preload="none"`, explicit lazy-load thresholds, intrinsic dimensions/aspect ratios, offscreen pause, safe size/duration caps, and accessible failure text.
+- Final scene and video states must satisfy the three-flashes-or-below-threshold rule.
+- WCAG acceptance must include 320 CSS-pixel reflow/400% zoom, text-spacing overrides, forced colors, unobscured focus, and named screen-reader/browser pairs.
+- The 44-by-44 CSS-pixel target applies to touch/pointer controls at every supported viewport, not mobile portrait only.
+
+### 10. Define the supported-browser and failure-injection matrix
+
+Required coverage should include current and previous Chromium, Firefox, and Safari/WebKit releases, plus at least one physical iOS Safari and Android Chromium check. Mobile checks cover rotation, dynamic toolbars, safe areas, background/foreground, sustained scrolling, memory pressure, audio interruption, and context loss.
+
+Fault injection should cover:
+
+- Three.js chunk failure;
+- shader compilation failure;
+- model, texture, poster, and video failure;
+- hydration-entry failure;
+- exceptions before and after the first scene frame;
+- WebGL loss during loading and while hidden;
+- Web Audio start rejection and interruption.
+
+Every failure must preserve the H1, all semantic sections, native anchors, contact action, private-link omissions, focus behavior, and one clear static fallback without unhandled rejections.
+
+### 11. Add a provider-neutral security and hosting contract
+
+Production responses require tested security controls, including a restrictive Content Security Policy, HSTS, `X-Content-Type-Options`, explicit `Referrer-Policy`, least-privilege `Permissions-Policy`, and anti-framing protection. Hosting must support HTTPS/preferred-host redirects, Brotli/Gzip, immutable caching for hashed assets, HTML revalidation, correct MIME and media range responses, deployment verification, and rollback.
+
+Preview/staging must be authenticated where possible and additionally use `X-Robots-Tag: noindex, nofollow, noarchive`; it must not publish a production sitemap or enter Search Console.
+
+Production source maps are not public. External SVGs and media are untrusted, sanitized, and prevented from making external requests. Contact and social deployment values use allowlisted schemes and exact hosts, safe JSON-LD serialization, and `noopener`/referrer protections.
+
+### 12. Add supply-chain and provenance gates
+
+- exact lockfile and reproducible clean builds;
+- dependency and secret scanning with an explicit severity policy;
+- pinned CI actions;
+- SBOM generation;
+- no CDN or hotlinked executable assets;
+- no unreviewed post-install scripts;
+- local, licensed fonts and icons recorded in the asset register;
+- preserved MIT notice if reference code is substantially adapted.
+
+### 13. Split build-ready and deployed-production acceptance
+
+Build acceptance can verify semantic HTML, privacy gates, static fallback, validated structured data inputs, accessibility, performance budgets, and browser behavior.
+
+Deployment acceptance separately verifies production headers, canonical URL, preferred-host redirects, indexability, sitemap, media range requests, and post-deployment Search Console submission. Search Console is not a pre-build gate.
+
+### 14. Resolve smaller contradictions and define audience validation
+
+- H1 is exactly **Luca Pîslaru**; the role is an adjacent visible subtitle. The page title contains both name and role.
+- Domain and contact email are required. Each social profile is independently optional; visible links and JSON-LD `sameAs` entries are emitted only for configured, verified profiles.
+- The primary contact action is an ordinary `mailto:` link with a visible email fallback and no form backend.
+- The no-public-CV decision remains. Provide complete on-page experience details and a print-friendly portfolio view without presenting it as a downloadable résumé.
+- Run a small evidence-first audience check: representative hiring managers and technical interviewers should identify the name, equal hybrid role, contact path, and at least two credible proof points in a short static/reduced-motion review. Animation must not delay or obscure any answer.
+
+## Recommendations deliberately not adopted
+
+### Defer audio to a later release
+
+Not adopted. Interactive audio is an explicitly approved part of the experience. It remains optional, starts only after direct activation, never gates content, and gains a precise lifecycle and failure model.
+
+### Add a public CV download
+
+Not adopted. The absence of a public CV is an explicit privacy and contact choice. The specification should instead make the on-page professional record complete and printable, and make the email path frictionless.
+
+### Add general analytics for Core Web Vitals
+
+Not adopted for the initial release. Lab budgets become release gates; field p75 values remain goals. Any future RUM design requires a separate privacy review and strict data minimization.
+
+## Recommended next action
+
+Proceed to implementation planning from the approved Revision 8 specification. Preserve its product direction and translate the acceptance gates into phased, testable work rather than reopening aesthetic discovery.