Published and updated 31 July 2026 · Quality, Security, and Shipping
Published and updated 31 July 2026 · Quality, Security, and Shipping
Quality, Security, and Shipping: Test, Audit, Measure, Observe, Deploy, and Evolve connects the essential decisions in this stage of frontend engineering. You will learn each browser or framework model from first principles, apply it to the progressive Learning Atlas product, diagnose a realistic failure from evidence, and direct an AI collaborator with explicit constraints. The goal is independent judgment, not memorized syntax.
You will advance a measurable and safely deployable Learning Atlas. By the end, you can explain every topic in this chapter, implement one focused slice per topic, adapt those slices under new constraints, and defend the result with browser evidence, strict types, accessibility checks, security boundaries, and a production build.
Bring forward learning-atlas/tests, CI configuration, security policy, and deployment runbook and the verification notes from the preceding chapter. Create a narrow Git branch, read the repository rules, and inspect existing changes before editing. When a tool or file is introduced for the first time, its purpose is explained before its syntax.
Use these project-orientation commands:
Before beginning Quality, Security, and Shipping: Test, Audit, Measure, Observe, Deploy, and Evolve, stop if the working tree contains files you do not understand. Do not delete, reset, or rewrite another person's work to make the lesson cleaner.
Quality is layered evidence. Types rule out shapes, lint enforces policies, tests exercise behavior, audits reveal user barriers, telemetry exposes production reality, and a rollback plan limits the cost of an incorrect release. The topics below are ordered because each creates evidence needed by the next. Experienced readers may jump to a topic, but should still complete its failure investigation and adaptation task.
Each test layer answers a different question. Types check contracts, lint checks policies, unit tests isolate logic, component tests exercise user behavior, integration tests cross boundaries, and end-to-end tests prove critical journeys. Risk determines the mix.
The current artifact for testing strategy: types, lint, unit, component, integration, and end-to-end is learning-atlas/tests/progress.test.ts. Before editing, predict the visible behavior and name the source of truth. Then implement or study this complete focused slice:
Scenario: A unit-tested formatter passes, but the production form sends a different field name and no integration test crosses that boundary.
Evidence to collect: Map the incident to the earliest layer that could detect it realistically, inspect test inputs versus real protocol, and add one regression at that boundary.
Minimal repair rule: For testing strategy: types, lint, unit, component, integration, and end-to-end, correct the first boundary that violates the documented model, preserve the rest of the working path, and add a regression check based on the observed evidence.
Build a risk-to-test matrix for a mutation and defend which behaviors do not deserve end-to-end coverage.
An accessibility audit combines automation with human interaction. Keyboard testing reveals reach and order; screen readers expose names, roles, states, structure, and announcements; zoom and reflow expose layout barriers. Automated tools find only a subset.
The current artifact for accessibility audits with keyboard, screen readers, and automated tools is notes/accessibility-audit.md. Before editing, predict the visible behavior and name the source of truth. Then implement or study this complete focused slice:
Scenario: Automation reports no violation, yet a dialog opens without moving focus and screen-reader users continue reading the page behind it.
Evidence to collect: Record a keyboard transcript, screen-reader speech, focus before/open/close, accessibility tree, zoom behavior, and automation result.
Minimal repair rule: For accessibility audits with keyboard, screen readers, and automated tools, correct the first boundary that violates the documented model, preserve the rest of the working path, and add a regression check based on the observed evidence.
Audit one complete journey, rank barriers by user impact, repair the top issue, and repeat the same transcript.
Performance work begins with a user scenario and trace. Measure LCP, INP, CLS, server timing, requests, and JavaScript cost; identify the largest causal bottleneck; change one thing; compare distributions. Server-first rendering and smaller client graphs often help.
The current artifact for performance engineering: measure first, bundle less, render intentionally is learning-atlas/app/reportWebVitals.ts. Before editing, predict the visible behavior and name the source of truth. Then implement or study this complete focused slice:
Scenario: A developer memoizes every component, increasing code and comparison work while the actual LCP delay is an unoptimized image request.
Evidence to collect: Inspect field data, trace LCP phases, network priority, image candidate, long tasks, server timing, and bundle composition before editing components.
Minimal repair rule: For performance engineering: measure first, bundle less, render intentionally, correct the first boundary that violates the documented model, preserve the rest of the working path, and add a regression check based on the observed evidence.
Capture a baseline under constrained mobile conditions, predict the top bottleneck, make one change, and report evidence plus tradeoff.
Frontend security protects trust boundaries. Escape untrusted output, avoid unsafe HTML sinks, validate server inputs, use same-site and anti-CSRF controls where needed, keep secrets server-side, set defense-in-depth headers, and maintain dependencies without blind upgrades.
The current artifact for frontend security: xss, csrf, injection, secrets, headers, and dependencies is learning-atlas/next.config.ts. Before editing, predict the visible behavior and name the source of truth. Then implement or study this complete focused slice:
Scenario: A markdown preview passes user HTML to an unsafe rendering sink, allowing an injected event handler to run in another viewer's session.
Evidence to collect: Trace untrusted input to DOM sink, inspect sanitization policy and CSP, test an inert attack string, review cookies and affected privileges.
Minimal repair rule: For frontend security: xss, csrf, injection, secrets, headers, and dependencies, correct the first boundary that violates the documented model, preserve the rest of the working path, and add a regression check based on the observed evidence.
Threat-model one content feature, list sources and sinks, then remove or constrain the highest-impact path and add a regression test.
Observability connects a user-visible failure to system evidence. Structured logs record events, metrics show distributions, traces connect boundaries, and error reports preserve actionable context. Collect only necessary data, redact sensitive values, and use stable request IDs.
The current artifact for observability: useful logs, web vitals, errors, traces, and user context is learning-atlas/lib/telemetry.ts. Before editing, predict the visible behavior and name the source of truth. Then implement or study this complete focused slice:
Scenario: A production error report says failed without route, release, request ID, user action, or upstream status, so it cannot be reproduced.
Evidence to collect: Follow one request ID through browser event, server log, dependency trace, release version, duration, and redacted error context.
Minimal repair rule: For observability: useful logs, web vitals, errors, traces, and user context, correct the first boundary that violates the documented model, preserve the rest of the working path, and add a regression check based on the observed evidence.
Define five structured events for a core journey and explain retention, redaction, sampling, alert, and debugging use.
Deployment promotes a tested immutable artifact through environments with controlled configuration. Preview environments enable review but still need access and data rules. Safe releases define health checks, migration order, stop conditions, monitoring, and a rehearsed rollback.
The current artifact for deployment, preview environments, environment safety, and rollback is notes/release-runbook.md. Before editing, predict the visible behavior and name the source of truth. Then implement or study this complete focused slice:
Scenario: A preview uses production credentials and sends a test notification to real customers because configuration scope was copied wholesale.
Evidence to collect: Inspect environment bindings, secret scopes, data endpoints, outbound integration flags, artifact identity, deployment log, and notification audit.
Minimal repair rule: For deployment, preview environments, environment safety, and rollback, correct the first boundary that violates the documented model, preserve the rest of the working path, and add a regression check based on the observed evidence.
Write a release plan with preview isolation, smoke tests, migration compatibility, stop conditions, rollback steps, and responsible owner.
CI reproduces agreed checks in a clean environment; CD promotes artifacts under explicit policy. Gates should be deterministic, risk-based, and fast enough to run. AI may classify failures or propose repairs, but it must not bypass controls or approve its own unverified work.
The current artifact for ci/cd quality gates and ai-assisted maintenance is .github/workflows/quality.yml. Before editing, predict the visible behavior and name the source of truth. Then implement or study this complete focused slice:
Scenario: An AI maintenance job updates snapshots to make tests green, hiding a real accessible-name regression.
Evidence to collect: Compare changed behavior, snapshot diff, test intent, agent permissions, approval trail, clean CI log, and protected-branch rules.
Minimal repair rule: For ci/cd quality gates and ai-assisted maintenance, correct the first boundary that violates the documented model, preserve the rest of the working path, and add a regression check based on the observed evidence.
Design a maintenance workflow that may open a narrow pull request but cannot merge, access production secrets, or weaken a gate.
Sustainable architecture keeps change affordable through explicit boundaries, current dependencies, tests, decision records, and planned debt. Upgrade from release notes and a baseline, migrate one boundary at a time, and distinguish deliberate debt from unexplained disorder.
The current artifact for upgrades, migrations, technical debt, and sustainable frontend architecture is notes/upgrade-plan.md. Before editing, predict the visible behavior and name the source of truth. Then implement or study this complete focused slice:
Scenario: A framework upgrade combines runtime, router, styling, and component rewrites, making the first regression impossible to isolate.
Evidence to collect: Establish baseline tests and metrics, read migration guidance, inventory deprecated APIs, separate commits by boundary, and compare after each.
Minimal repair rule: For upgrades, migrations, technical debt, and sustainable frontend architecture, correct the first boundary that violates the documented model, preserve the rest of the working path, and add a regression check based on the observed evidence.
Create a migration sequence for one dependency with characterization tests, compatibility bridge, rollback, and removal criteria.
Goal: Advance a measurable and safely deployable Learning Atlas through one learning outcome at a time while keeping the implementation understandable and reversible.
Context to attach: the current quality, security, and shipping outcome, the product brief, repository rules, package versions, relevant files and callers, shared types or tokens, the current Git diff, and the latest observed failure or command output.
Constraints: while advancing a measurable and safely deployable Learning Atlas, preserve concurrent work; use semantic HTML and strict TypeScript; keep Server Components as the default in Next.js; validate untrusted data on the server; do not expose secrets; include loading, empty, error, success, disabled, and partial states when relevant; make one bounded change.
Acceptance criteria: the quality, security, and shipping adaptation works from 320 pixels upward; keyboard and focus behavior are complete; color is not the only signal; authorization and validation are enforced at authoritative boundaries; the relevant type, lint, build, and browser checks pass.
Reusable prompt:
We are implementing one outcome from “Quality, Security, and Shipping: Test, Audit, Measure, Observe, Deploy, and Evolve” in the Learning Atlas. Read the attached repository rules, outcome text, relevant files, current diff, and verification evidence. Restate the user-visible result, source of truth, trust boundary, valid states, and unknowns. Propose the smallest reversible vertical slice. Implement only that slice. Then report the exact diff, criterion-to-evidence mapping, remaining risks, and the next discriminating check. Stop before dependency installation, destructive action, public-contract change, authentication decision, or deployment unless explicitly authorized.
For Quality, Security, and Shipping: Test, Audit, Measure, Observe, Deploy, and Evolve, inspect the response without relying on its summary. Read every changed line, compare it with the actual source of truth, and reproduce the evidence yourself. Reject unexplained assertions, broad client boundaries, missing states, invented APIs, suppressed errors, or tests that merely restate implementation details.
A preview release passes lint but fails keyboard use, exposes unsafe HTML, increases LCP, and cannot roll back after a migration. Build a causal timeline across gates, telemetry, environment, and artifact history. Write exact reproduction steps and expected versus observed behavior. Follow the value across every relevant boundary until you find the first contradiction.
Within the design and verify stage of Quality, Security, and Shipping: Test, Audit, Measure, Observe, Deploy, and Evolve, change one cause, not several symptoms. Rerun the original reproduction, one adjacent failure case, keyboard navigation, and the focused static checks. The lab is complete only when you can explain why the repair works and which regression check would have failed before it.
Run the scripts that this project actually defines:
If your learning project later defines a test script, run it as an additional gate; do not report tests as passing when no test command exists. In the browser, run every quality gate from a clean checkout, inspect production output, test rollback, and attach results to the change. Repeat the primary journey at 320, 768, and wide desktop widths, at 200% zoom, in both themes, by keyboard, and with reduced motion. For networked work, simulate slow, malformed, unauthorized, empty, and failed responses.
Close Quality, Security, and Shipping: Test, Audit, Measure, Observe, Deploy, and Evolve and draw its models from memory. Pick two outcomes and explain how a decision in the first can cause a failure in the second. Then complete three levels of practice:
You have treated quality, security, and shipping as a connected engineering system rather than isolated syntax. The durable result is not the example code; it is the ability to predict behavior, expose assumptions, collect evidence, bound AI work, and repair the first broken boundary. Carry the product files and evidence log into the next stage.