# Design — phase-7-devops-field-trial

**Status:** Complete  
**Archived:** 2026-04-04

## Context

`docs/devops/` was last updated during Phase 2. Phases 3–6 added 14 new DB migrations, Phase 6 feature flags (ANALYTICS_ENABLED, TIER_ENFORCEMENT, COMPLIANCE_ENABLED), Stripe integration (STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET), new services (Analytics, Tier, Compliance, A2A), the Next.js portal, and substantial changes to env var requirements. The DevOps documentation did not reflect any of these changes.

Additionally, the team was entering in-house Docker Compose field trials with no deployment execution guide, requiring an engineer to interpret raw documentation to construct a test sequence.

## Goals / Non-Goals

**Goals:**
- Bring all 8 `docs/devops/` files current with Phase 6 codebase state
- Create `docs/devops/field-trial.md` — a complete step-by-step execution playbook for in-house field trials
- Field trial guide must be self-contained: an engineer on a clean machine can follow it without asking questions

**Non-Goals:**
- Not a production deployment guide (that is existing deployment.md)
- Not a developer quickstart (that is docs/developers/quick-start.md)
- No changes to src/ code or infrastructure

## Decisions

### D1: Update existing files in place
The 8 existing devops docs are updated surgically — new env vars added to environment-variables.md, new tables added to database.md, etc. Existing content is not restructured.

### D2: field-trial.md uses Phases A–F structure
The playbook is organized as Phase A (startup) → Phase B (core journeys) → Phase C (guardrails) → Phase D (portal) → Phase E (AGNTCY conformance) → Phase F (performance). Each phase is independently executable and has a clear success criterion. A failure in Phase A (stack does not start) blocks all subsequent phases.

### D3: All steps are copy-paste executable
Every step in field-trial.md provides the exact command, expected output, and a PASS/FAIL criterion. No step requires inference or judgment from the engineer.

### D4: Troubleshooting section included
field-trial.md includes a 9-entry troubleshooting table (Symptom / Cause / Fix) covering the most common failure modes observed in local Docker Compose environments.