7441c9f298
All findings from the inaugural LeadValidator audit resolved and confirmed. Release gate: PASS. VV_ISSUE_002 (BLOCKER): 15 OpenAPI specs verified present covering all 20 route groups (46 endpoints documented in docs/openapi/) VV_ISSUE_003 (MAJOR): Remove any types from src/db/pool.ts — replaced pool.query shim with unknown[] + Object.defineProperty, zero any types, eslint-disable suppressions removed VV_ISSUE_004 (MAJOR): Remove raw Pool from ScaffoldController and HealthDetailedController — injected AgentRepository/CredentialRepository and DbProbe interface respectively; added CredentialRepository.findActiveClientId() VV_ISSUE_005 (MAJOR): Add unit tests for 5 untested services — ComplianceStatusStore, EventPublisher, MarketplaceService, OIDCTrustPolicyService, UsageService VV_ISSUE_006 (MAJOR): Add integration tests for 7 missing route groups — analytics, billing, tiers, webhooks, marketplace, oidc-trust-policies, oidc-token-exchange VV_ISSUE_001 (MINOR): Create missing design.md and tasks.md in 4 OpenSpec archives — all archives now complete Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
37 lines
2.2 KiB
Markdown
37 lines
2.2 KiB
Markdown
# 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.
|