fix(vv): resolve all 6 V&V issues — field trial unblocked

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>

openspec/changes/archive/2026-04-02-engineering-docs/tasks.md

@@ -0,0 +1,26 @@
+## Engineering Docs — Task Tracker
+
+All tasks complete. Archive committed 2026-04-02.
+
+### WS1 — Core Knowledge Base (10 documents)
+
+- [x] 1.1 Create `docs/engineering/README.md` — directory index and reading path
+- [x] 1.2 Create `docs/engineering/01-overview.md` — company mission, product vision, system purpose, team structure
+- [x] 1.3 Create `docs/engineering/02-architecture.md` — component diagram, data flows, deployment topology, technology rationale
+- [x] 1.4 Create `docs/engineering/03-tech-stack.md` — full stack with ADRs (Express, PostgreSQL, Redis, TypeScript, OPA, Vault)
+- [x] 1.5 Create `docs/engineering/04-codebase-structure.md` — annotated directory map covering all top-level directories and key files
+- [x] 1.6 Create `docs/engineering/05-services.md` — deep dives for AgentService, OAuth2Service, CredentialService, AuditService, VaultClient, OPA engine, Web Dashboard, Prometheus/Grafana
+- [x] 1.7 Create `docs/engineering/06-walkthroughs.md` — annotated traces for token issuance, agent registration, and credential rotation (with file:line references)
+- [x] 1.8 Create `docs/engineering/07-dev-setup.md` — < 30 min onboarding from clone to running local stack
+- [x] 1.9 Create `docs/engineering/08-workflow.md` — OpenSpec → Architect → Developer → QA → merge cycle and PR standards
+- [x] 1.10 Create `docs/engineering/09-testing.md` — framework, test types, coverage gates, how to run and write tests
+
+### WS2 — Operations and Integration
+
+- [x] 2.1 Create `docs/engineering/10-deployment.md` — Docker build/run, Terraform multi-region, env config, monitoring runbooks
+- [x] 2.2 Create `docs/engineering/11-sdk-guide.md` — Node.js, Python, Go, Java SDK integration with installation, auth, operations, error handling
+
+### WS3 — Quality and Review
+
+- [x] 3.1 CTO review — all documents reviewed against PRD standards (calibration, accuracy, completeness)
+- [x] 3.2 QA sign-off — cross-link validation, code example verification

openspec/changes/archive/developer-docs-phase6-update/design.md

@@ -0,0 +1,36 @@
+# Design — developer-docs-phase6-update
+
+**Status:** Complete  
+**Archived:** 2026-04-04
+
+## Context
+
+Developer documentation in `docs/developers/` was last updated during Phase 2. The current product surface (Phase 6) includes ~25+ endpoints across organizations, analytics, tiers, billing, OIDC, A2A delegation, DID identity, webhooks, federation, and marketplace — none of which appear in the published developer docs. External developers attempting to use Phase 3–6 features have no reference.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Bring all developer-facing docs current with Phase 6 surface
+- Update API reference to cover all 50+ endpoints (was 14)
+- Add Phase 3–6 concepts to concepts.md
+- Update quick-start to reflect org-first registration flow
+- Add 5 new guides for Phase 3–6 features
+
+**Non-Goals:**
+- Not a rewrite — existing Phase 1–2 content is preserved and extended
+- Not engineering internals — this is for external developers, not contributors
+- No changes to `docs/engineering/` or `docs/devops/`
+
+## Decisions
+
+### D1: Extend, don't replace
+Existing content in concepts.md, quick-start.md, and guides/ is preserved as-is. New sections are appended. This avoids breaking any existing bookmarks or references.
+
+### D2: Single api-reference.md, complete replacement
+The 14-endpoint Phase 1 api-reference.md is replaced wholesale — it covers less than 30% of the surface and retrofitting 50+ endpoint sections into its structure is cleaner as a full rewrite.
+
+### D3: One guide per Phase 3–6 feature surface
+New guides added: `use-analytics-dashboard.md`, `manage-api-tiers.md`, `a2a-delegation.md`, `configure-webhooks.md`, `agntcy-compliance.md`. Each follows the existing guide format: overview, prerequisites, step-by-step with curl examples.
+
+### D4: README.md index updated
+`docs/developers/README.md` guide index expanded from 4 to 9 entries to include all new guides.

openspec/changes/archive/developer-docs-phase6-update/tasks.md

@@ -0,0 +1,46 @@
+## developer-docs-phase6-update — Task Tracker
+
+All tasks complete. Archive committed 2026-04-04.
+
+### WS1 — api-reference.md (complete replacement)
+
+- [x] 1.1 Remove Phase 1 content (14 endpoints)
+- [x] 1.2 Document all 50+ current endpoints across 13 endpoint groups with method, path, auth, request/response schemas, error codes, and curl examples
+- [x] 1.3 Groups covered: Agents, Credentials, OAuth2 Token, Audit, Organizations, DID, Federation, Webhooks, Marketplace, Billing, Tiers, Analytics, OIDC/Delegation
+
+### WS2 — concepts.md (6 new sections appended)
+
+- [x] 2.1 Add Organizations & Multi-tenancy section
+- [x] 2.2 Add DID Identity (did:web) section
+- [x] 2.3 Add OIDC Provider section
+- [x] 2.4 Add A2A Delegation section
+- [x] 2.5 Add API Tier Plans section (Free/Pro/Enterprise)
+- [x] 2.6 Add AGNTCY Compliance section
+
+### WS3 — quick-start.md (org-first flow)
+
+- [x] 3.1 Add Step 0: Create API key / account
+- [x] 3.2 Add Step 1: Create organization (now required before agent registration)
+- [x] 3.3 Renumber all existing steps
+- [x] 3.4 Update agent registration curl to include `organization_id`
+
+### WS4 — guides/ (4 updated + 5 new)
+
+- [x] 4.1 Update `authenticate-agent.md` — add org-scoped token request
+- [x] 4.2 Update `rotate-credentials.md` — verify paths current
+- [x] 4.3 Update `query-audit-logs.md` — add org filter param
+- [x] 4.4 Update `manage-agents.md` — add `organization_id` to all requests
+- [x] 4.5 Create `use-analytics-dashboard.md`
+- [x] 4.6 Create `manage-api-tiers.md`
+- [x] 4.7 Create `a2a-delegation.md`
+- [x] 4.8 Create `configure-webhooks.md`
+- [x] 4.9 Create `agntcy-compliance.md`
+
+### WS5 — README.md
+
+- [x] 5.1 Fix "bedroom developers" typo → "developers"
+- [x] 5.2 Expand guide index from 4 to 9 entries
+
+### QA
+
+- [x] 6.1 QA sign-off — 24/24 gates PASS, no defects

openspec/changes/archive/engineering-docs-phase6-update/design.md

@@ -0,0 +1,36 @@
+# Design — engineering-docs-phase6-update
+
+**Status:** Complete  
+**Archived:** 2026-04-04
+
+## Context
+
+`docs/engineering/` (12 files) was created during Phase 2 to onboard new engineers. Phases 3–6 shipped 9 new services, the Rust SDK, 14 new database migrations, and significant architectural changes (Next.js portal, analytics pipeline, tier enforcement, A2A delegation, federation, OIDC, DID). None of these appear in the engineering documentation. An engineer reading the Phase 2 docs would have an inaccurate picture of the system.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Bring all 12 engineering docs current with Phase 6 codebase state
+- Add service deep dives for all 9 Phase 3–6 services
+- Update architecture diagram to include portal, tier layer, analytics pipeline
+- Add complete Rust SDK section to sdk-guide.md
+- Update testing.md with AGNTCY conformance suite and Phase 6 test matrix
+
+**Non-Goals:**
+- Not a rewrite of Phase 1–2 content (existing sections preserved)
+- Not developer-facing API docs (that is docs/developers/)
+- No changes to src/ code
+
+## Decisions
+
+### D1: Append-only for most files
+Phase 2 content is accurate for Phase 1–2 features. New Phase 3–6 content is appended to avoid disturbing existing references. Exception: architecture.md component diagram is updated in-place (the diagram describes the full system).
+
+### D2: Service deep-dive format is standardized
+Each new service deep dive in 05-services.md follows the existing format: Purpose, Public Methods (table), Dependencies, Redis Keys, DB Tables. This ensures consistency and fast lookup for engineers.
+
+### D3: Rust SDK gets its own section (not a new file)
+The Rust SDK section is appended to 11-sdk-guide.md as Section 6, keeping all SDK documentation in one place. Existing Section 6 (Contribution Guide) is renumbered to Section 7.
+
+### D4: Three new sequence diagrams added
+02-architecture.md gains three Mermaid sequence diagrams: Analytics Event Capture, Tier Enforcement Middleware Chain, and A2A Delegation end-to-end. These cover the most complex new flows.

openspec/changes/archive/engineering-docs-phase6-update/tasks.md

@@ -0,0 +1,46 @@
+## engineering-docs-phase6-update — Task Tracker
+
+All tasks complete. Archive committed 2026-04-04.
+
+### WS1 — 05-services.md (9 Phase 3–6 service deep dives)
+
+- [x] 1.1 Add AnalyticsService deep dive (purpose, recordEvent/getTrend/getActivity, Redis keys, analytics_events table)
+- [x] 1.2 Add TierService deep dive (getStatus/initiateUpgrade/applyUpgrade, tenant_tiers table, Stripe webhook integration)
+- [x] 1.3 Add ComplianceService deep dive (5 AGNTCY controls, ComplianceStatusStore, compliance_status table)
+- [x] 1.4 Add FederationService deep dive (federation registry, trust anchors, agent verification)
+- [x] 1.5 Add DIDService deep dive (DID:WEB generation, resolution, audit integration)
+- [x] 1.6 Add WebhookService deep dive (subscription CRUD, EventPublisher integration, delivery retry)
+- [x] 1.7 Add BillingService deep dive (Stripe checkout, webhook handling, tier upgrade flow)
+- [x] 1.8 Add OIDCService deep dive (well-known endpoints, agent-info, JWT signing via OIDCKeyService)
+- [x] 1.9 Add DelegationService deep dive (A2A delegation chains, scope constraints, trust verification)
+
+### WS2 — 02-architecture.md (component diagram + 3 sequence diagrams)
+
+- [x] 2.1 Update component diagram: add tierMiddleware, Next.js portal, Stripe, OIDC provider
+- [x] 2.2 Add Mermaid sequence diagram: Analytics Event Capture
+- [x] 2.3 Add Mermaid sequence diagram: Tier Enforcement Middleware Chain
+- [x] 2.4 Add Mermaid sequence diagram: A2A Delegation end-to-end
+
+### WS3 — 11-sdk-guide.md (Rust SDK section)
+
+- [x] 3.1 Add Section 6: Rust SDK (sdk-rust/) — Cargo.toml installation, full working example, client method reference, error types
+- [x] 3.2 Renumber old Section 6 (Contribution Guide) to Section 7
+
+### WS4 — 09-testing.md (Phase 6 test coverage)
+
+- [x] 4.1 Add AGNTCY Conformance Suite section (4 tests, run command)
+- [x] 4.2 Add Tier Enforcement Tests section
+- [x] 4.3 Add Analytics Service Tests section
+- [x] 4.4 Add Complete Phase 6 Test Matrix
+
+### WS5 — Remaining 5 files
+
+- [x] 5.1 Update `01-overview.md` — Phase 3–6 roadmap entries + 10 new product feature rows + 3-tier limits table
+- [x] 5.2 Update `03-tech-stack.md` — 5 new ADRs (Stripe, oidc-provider, Next.js 14, bull/kafkajs, did-resolver)
+- [x] 5.3 Update `04-codebase-structure.md` — sdk-rust/, portal/, tests/agntcy-conformance/ added to directory tree
+- [x] 5.4 Update `06-walkthroughs.md` — 3 new walkthroughs (A2A Delegation, Tier Enforcement, Analytics Event Capture)
+- [x] 5.5 Update `README.md` — 17 services, 5 SDKs, ~4 hours total reading time, 5 new Quick Reference rows
+
+### QA
+
+- [x] 6.1 QA sign-off — 23/23 gates PASS, no defects

openspec/changes/archive/phase-7-devops-field-trial/design.md

@@ -0,0 +1,36 @@
+# 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.

openspec/changes/archive/phase-7-devops-field-trial/tasks.md

@@ -0,0 +1,33 @@
+## phase-7-devops-field-trial — Task Tracker
+
+All tasks complete. Archive committed 2026-04-04.
+
+### WS1 — Update Existing DevOps Docs (8 files)
+
+- [x] 1.1 `environment-variables.md` — add 17 new variable blocks (Billing/Stripe, Phase 6 feature flags, Redis rate-limit, DB pool, OPA, Kafka, TLS enforcement); replace complete .env example
+- [x] 1.2 `database.md` — update schema diagram to show all 26 tables; add new table definitions for analytics_events, tenant_tiers, delegation_chains, and all Phase 3–5 tables
+- [x] 1.3 `deployment.md` — add Phase 3–6 env vars to quick-reference table
+- [x] 1.4 `local-development.md` — add nvm activation step; add Step 7 for Next.js portal startup
+- [x] 1.5 `operations.md` — document 19 Prometheus metrics; update Redis key patterns with tier counters and compliance cache; add 4 new troubleshooting entries
+- [x] 1.6 `architecture.md` — add Next.js portal to diagram; document 14 new services; list all 25 API routes
+- [x] 1.7 `security.md` — minor targeted updates (Stripe webhook verification, OIDC trust policies)
+- [x] 1.8 `vault-setup.md` — minor targeted updates (new secret paths for Phase 3–6)
+
+### WS2 — New Field Trial Guide
+
+- [x] 2.1 Create `docs/devops/field-trial.md` — prerequisites + Section 0 (RSA key generation, .env setup)
+- [x] 2.2 Phase A: Stack startup (Docker Compose + 26 migrations)
+- [x] 2.3 Phase B: Core product journeys (8 steps — org → agent → credentials → token → verify → rotate → audit)
+- [x] 2.4 Phase C: Security guardrails (7 tests — auth, rate limit, tier limit, tenant isolation)
+- [x] 2.5 Phase D: Next.js portal verification (9 routes)
+- [x] 2.6 Phase E: AGNTCY conformance suite (4 protocol tests)
+- [x] 2.7 Phase F: Performance baseline (Apache Bench, token <100ms, API <200ms targets)
+- [x] 2.8 Troubleshooting section (9 entries with Symptom/Cause/Fix)
+
+### WS3 — README Index
+
+- [x] 3.1 `README.md` — add field-trial.md to document index
+
+### QA
+
+- [x] 4.1 QA sign-off — 15/15 gates PASS