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>
2.2 KiB
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.