Legacy safety rails

Legacy Safety Rails

Build the protective infrastructure that makes legacy refactoring safe: tests, observability, feature flags, and rollback plans.

Goal

Create a multi-layer safety net so that any future code change can be verified, monitored, and reversed.

When to Use

• After documentation exists (via legacy-doc-bootstrap)
• Before any refactoring or modernization work begins
• When the user wants to "make this safe to change"
• When critical paths lack test coverage

The Five Guardrail Layers

Layer 1: Behavior Baseline

Capture current behavior as the source of truth.

• API responses: Record request/response pairs for key endpoints
• UI state: Screenshots or snapshots of critical pages/states
• Data contracts: Current schemas, field types, required fields
• Performance baseline: Response times, throughput for P0 paths
• Side effects: What external calls happen (emails, webhooks, analytics events)
• Runtime behavior: Actual call chains, feature flag states, real data shapes (see docs/methodology.md → Runtime Behavior Capture)

Layer 2: Test Guardrails

Priority order (NOT "write all unit tests first"):

1. Characterization tests — capture actual behavior as golden files/snapshots, including bug behavior that downstream may depend on. See docs/methodology.md → Characterization Testing.
2. P0 path integration tests — end-to-end for critical user journeys
3. Business rule module tests — isolated tests for core business logic
4. Contract tests — API schemas, database schemas, message formats (see Contract-First below)
5. Smoke tests — basic "does it start and respond" health checks

Characterization test rules:

• Capture reality, not intent. Do not "fix" tests to match expectations.
• Include edge cases: empty input, null values, boundary conditions, error responses.
• Tools: snapshot testing (Jest snapshots, approval tests), API recording (VCR/Nock/Polly.js).
• After refactoring, these tests catch unintended behavior changes — even "bug fixes" that break downstream.

Layer 3: Compatibility Guardrails

Protect interfaces and contracts using a contract-first approach (see docs/methodology.md → Contract-First Boundary Definition):

• API contracts: OpenAPI spec / JSON Schema for HTTP interfaces
• Data contracts: TypeScript interfaces or JSON Schema for data structures
• Event contracts: Schema for events/messages between modules
• Database contracts: Migration-versioned schema expectations
• Error codes and error message formats
• Default values and fallback behaviors

Key rule: Contracts must be tested (Layer 2 contract tests). Untested contracts are just documentation.

Layer 4: Release Guardrails

Mechanisms for safe deployment:

• Feature flags for new code paths
• Gradual rollout / canary deployment strategy
• Shadow mode (new code runs but old code serves)
• Rollback procedure (documented, tested)

Layer 5: Change Guardrails

Per-change safety checklist:

• Impact scope documented
• Verification method defined
• Rollback method defined
• Human approval obtained for flagged changes

Mandatory Workflow

Step 1: Assess Existing Safety Infrastructure

1. What test framework is in use? What version?
2. What tests exist? What do they cover?
3. Is there CI/CD? What checks run on commit/deploy?
4. Are there feature flags, monitoring, or alerting?
5. What's the current deployment/rollback process?
6. Check project type from discovery outputs. Load the corresponding profile from skills/legacy-discovery/profiles/ to understand stack-specific testing tools and guardrail priorities.

Step 2: Prioritize by Risk

Using discovery risk labels:

Label	Safety Action
P0-CRITICAL	Layer 1 (baseline) + Layer 2 (integration test) + Layer 4 (rollback)
HIGH-RISK	Layer 2 (module tests) + Layer 3 (contracts)
TEST-MISSING	Layer 2 (appropriate test type)
LEGACY-SEALED	Layer 1 (baseline only — don't touch)
SAFE-TO-EXTRACT	Layer 2 (module tests before extraction)

Step 3: Build Guardrails Incrementally

For each domain/module in scope:

1. Capture baseline — record current behavior
2. Write highest-priority tests — based on risk assessment
3. Document contracts — lock down interfaces
4. Define rollback procedure — before any refactor begins
5. Set up feature flags — if the project's tech stack supports them

Step 4: Verify Guardrails Work

• Run all new tests. They must pass against current code.
• Intentionally break something small — verify tests catch it.
• Document what each guardrail protects.

Step 5: Update Documentation

Add test baseline info to docs/legacy-modernization/domains/<domain>/test-baseline.md. Record module-to-test mapping for every guarded source file and make the edit gate explicit (ALLOW / BLOCKED-TEST-MISSING / BLOCKED-DOC-MISSING).

Required Outputs

Output	Description
Test inventory	What tests were added, what they cover, what's still missing
Contract registry	Documented API/schema/event contracts
Baseline snapshots	Captured behavior baselines with storage location
Rollback plan	Step-by-step rollback procedure for each area
Coverage gap report	What's still unprotected, prioritized by risk
Feature flag plan	What flags are needed for upcoming changes

Hard Rules

1. Match the existing stack. Write tests using the project's existing test framework and version. Don't introduce new test frameworks without discussion.
2. Lockfile versions apply. If the project uses Jest 27, write Jest 27-compatible tests. Don't use Jest 29 APIs.
3. Tests must pass today. Every test you write must pass against the current codebase. Failing tests are not guardrails.
4. Don't test implementation details. Test behavior and contracts, not internal structure.
5. Baseline before changing. Never skip behavior capture for a P0-CRITICAL module.
6. Rollback must be documented. Every guardrailed area needs a written rollback procedure.
7. Don't boil the ocean. You don't need 100% coverage. You need coverage on the paths that matter.
8. Create module-to-test mapping. The guardrail is incomplete until each protected module points to concrete tests.
9. Block source edits when tests are missing. If a module is still TEST-MISSING, document that the edit gate remains closed.

Profile-Specific Guardrail Guidance

The project type (detected during discovery) determines which guardrails matter most. Consult the profile for stack-specific tools and approaches.

Frontend Projects (profiles/frontend.md)

Layer	Focus
Behavior baseline	Screenshot snapshots of key pages/states, Core Web Vitals baseline (LCP, INP, CLS)
Test guardrails	Component tests (Testing Library), E2E tests (Playwright/Cypress), visual regression (Chromatic/Percy)
Compatibility guardrails	Component prop interfaces, API request/response types, CSS scope boundaries
Release guardrails	Feature flags (LaunchDarkly/Unleash/custom), A/B testing hooks, bundle size gate in CI
Change guardrails	Bundle size diff check, lighthouse CI, accessibility audit (axe-core)

Backend-Node Projects (profiles/backend-node.md)

Layer	Focus
Behavior baseline	API response recording (Nock/Polly.js), database state snapshots
Test guardrails	API integration tests (Supertest), middleware isolation tests, queue/worker tests
Compatibility guardrails	OpenAPI schema validation, database migration versioning, event schema contracts
Release guardrails	Feature flags, canary deployment, graceful shutdown verification
Change guardrails	npm audit in CI, health check endpoint verification

Backend-Java Projects (profiles/backend-java.md)

Layer	Focus
Behavior baseline	API response recording, database state with Testcontainers
Test guardrails	@SpringBootTest integration tests, MockMvc/RestAssured API tests, ArchUnit architecture tests
Compatibility guardrails	OpenAPI schema, Flyway/Liquibase migration versioning, message contract tests
Release guardrails	Spring Profiles for feature toggling, Actuator health checks, JVM metrics baseline
Change guardrails	OWASP dependency-check in CI, JaCoCo coverage gate

Backend-Python Projects (profiles/backend-python.md)

Layer	Focus
Behavior baseline	API response recording (VCR.py/responses), database state fixtures
Test guardrails	pytest integration tests, DRF APIClient/FastAPI TestClient, factory_boy fixtures
Compatibility guardrails	Schema validation (Pydantic/Marshmallow), Django migration lint, event contracts
Release guardrails	Feature flags (django-waffle/Unleash), health check endpoints
Change guardrails	pip-audit/safety in CI, coverage gate (pytest-cov)

Backend-Go Projects (profiles/backend-go.md)

Layer	Focus
Behavior baseline	API response recording, database state with testcontainers-go
Test guardrails	httptest API tests, table-driven tests, -race flag in CI, integration tests with build tags
Compatibility guardrails	protobuf/OpenAPI schema validation, migration versioning (golang-migrate/goose)
Release guardrails	Feature flags, graceful shutdown (signal.NotifyContext), health/ready endpoints
Change guardrails	govulncheck in CI, golangci-lint, benchmark regression tests

Fullstack Projects (profiles/fullstack.md)

Apply both frontend and backend layers, plus:

Layer	Focus
Behavior baseline	Full user journey recording spanning frontend and backend
Compatibility guardrails	Frontend-backend API contract tests (shared types or schema validation)
Release guardrails	Coordinated deploy strategy, deploy-order safety
Change guardrails	Contract drift detection between frontend types and backend responses

Anti-Patterns

Don't	Do instead
Write 200 unit tests for utility functions	Write 5 integration tests for P0 user journeys
Introduce a new test framework	Use the existing one at its actual version
Write tests that depend on internal state	Test observable behavior and public interfaces
Assume CI will catch everything	Verify tests actually run in CI
Skip rollback planning	Document rollback for every guardrailed area
Add guardrails to sealed modules	Capture baseline only — don't modify sealed code