feat(openspec): propose phase-6-market-expansion change

Analytics Dashboard, API Gateway Tiers, AGNTCY Compliance — 62 tasks across 8 groups.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

openspec/changes/phase-6-market-expansion/tasks.md

@@ -0,0 +1,76 @@
+## 1. Foundation & Database Migrations
+
+- [ ] 1.1 Create migration `023_add_analytics_events.sql` — `analytics_events(id, tenant_id, date, metric_type, count, PRIMARY KEY(tenant_id, date, metric_type))`
+- [ ] 1.2 Create migration `024_add_tenant_tiers.sql` — `tenant_tiers(tenant_id FK, tier ENUM('free','pro','enterprise'), created_at, updated_at)`
+- [ ] 1.3 Add `TIER_CONFIG` constant to `src/config/tiers.ts` with free/pro/enterprise limits
+- [ ] 1.4 Add `ANALYTICS_ENABLED`, `TIER_ENFORCEMENT`, `COMPLIANCE_ENABLED` env vars to `.env.example` and `src/config/env.ts`
+- [ ] 1.5 Run migrations in test environment and verify table creation
+
+## 2. WS3 — Analytics Backend
+
+- [ ] 2.1 Create `src/services/AnalyticsService.ts` — `recordEvent(tenantId, metricType)`, `getTokenTrend(tenantId, days)`, `getAgentActivity(tenantId)`, `getAgentUsageSummary(tenantId)` with JSDoc
+- [ ] 2.2 Add analytics event recording to `OAuth2Service.issueToken()` — fire-and-forget (non-blocking)
+- [ ] 2.3 Add analytics event recording to `AgentService.create()` and `AgentService.deactivate()`
+- [ ] 2.4 Create `src/controllers/AnalyticsController.ts` — GET /api/analytics/tokens, GET /api/analytics/agents/activity, GET /api/analytics/agents
+- [ ] 2.5 Create `src/routes/analytics.ts` and register under `/api/analytics` in `src/app.ts` (guarded by `ANALYTICS_ENABLED` flag)
+- [ ] 2.6 Add input validation: `days` param capped at 90, tenant scoping enforced on all queries
+
+## 3. WS3 — Analytics Portal Pages
+
+- [ ] 3.1 Add `recharts` and `date-fns` to `portal/package.json`
+- [ ] 3.2 Create `portal/src/components/charts/TokenTrendChart.tsx` — recharts LineChart, lazy-loadable
+- [ ] 3.3 Create `portal/src/components/charts/AgentHeatmap.tsx` — recharts custom heatmap, lazy-loadable
+- [ ] 3.4 Create `portal/src/pages/analytics/index.tsx` — uses `next/dynamic` for chart components, fetches from `/api/analytics/*`
+- [ ] 3.5 Add `/analytics` route to portal navigation (`portal/src/components/Sidebar.tsx` or equivalent)
+- [ ] 3.6 Verify `next build` succeeds and analytics chunk is separate from main bundle
+
+## 4. WS4 — API Gateway Tiers Backend
+
+- [ ] 4.1 Create `src/middleware/tierEnforcement.ts` — reads `req.tenant.tier`, checks Redis `rate:tier:calls:<tenant_id>` against `TIER_CONFIG`, sets rate limit headers on all responses
+- [ ] 4.2 Register `tierEnforcement` middleware in `src/app.ts` after auth middleware, before routes (skip when `TIER_ENFORCEMENT=false`)
+- [ ] 4.3 Add agent count enforcement in `AgentService.create()` — query active agent count vs. tier limit, throw typed `TierLimitError` if exceeded
+- [ ] 4.4 Create `src/services/TierService.ts` — `getStatus(tenantId)`, `initiateUpgrade(tenantId, targetTier)`, `applyUpgrade(tenantId, tier)` (called from Stripe webhook)
+- [ ] 4.5 Create `src/controllers/TierController.ts` — GET /api/tiers/status, POST /api/tiers/upgrade
+- [ ] 4.6 Create `src/routes/tiers.ts` and register under `/api/tiers` in `src/app.ts`
+- [ ] 4.7 Update Stripe webhook handler (`src/services/BillingService.ts`) to call `TierService.applyUpgrade()` on `checkout.session.completed` for tier upgrade events
+- [ ] 4.8 Add `TierLimitError` to error hierarchy in `src/errors/index.ts` — HTTP 429, `tier_limit_exceeded` code
+
+## 5. WS4 — Tier Portal Page
+
+- [ ] 5.1 Create `portal/src/pages/settings/tier.tsx` — displays current tier, limits, usage, upgrade button
+- [ ] 5.2 Upgrade button calls `POST /api/tiers/upgrade` and redirects to Stripe checkout URL
+- [ ] 5.3 Enterprise tier view shows "Unlimited" with no upgrade button
+- [ ] 5.4 Add `/settings/tier` to portal navigation
+
+## 6. WS6 — AGNTCY Compliance Backend
+
+- [ ] 6.1 Create `src/services/ComplianceService.ts` — `generateReport(tenantId)` building all compliance sections, `exportAgentCards(tenantId)`, Redis cache with 5-minute TTL
+- [ ] 6.2 Implement `agent-identity` section: check all active agents for valid DID, non-expired credential, agent card presence
+- [ ] 6.3 Implement `audit-trail` section: verify Merkle chain integrity for tenant's audit events
+- [ ] 6.4 Implement agent card export: map agent records to AGNTCY agent card JSON schema v1.0
+- [ ] 6.5 Create `src/controllers/ComplianceController.ts` — GET /api/compliance/report, GET /api/compliance/agent-cards
+- [ ] 6.6 Create `src/routes/compliance.ts` and register under `/api/compliance` in `src/app.ts` (guarded by `COMPLIANCE_ENABLED` flag)
+
+## 7. WS6 — AGNTCY Conformance Test Suite
+
+- [ ] 7.1 Create `tests/agntcy-conformance/` directory with Jest config
+- [ ] 7.2 Write conformance test: agent registration creates DID:WEB identifier
+- [ ] 7.3 Write conformance test: token issuance for agent client
+- [ ] 7.4 Write conformance test: A2A delegation chain create + verify
+- [ ] 7.5 Write conformance test: compliance report generation returns valid structure
+- [ ] 7.6 Add `test:agntcy-conformance` npm script to `package.json`
+
+## 8. QA & Release
+
+- [ ] 8.1 Write unit tests for `AnalyticsService` — event recording, trend query, heatmap query, usage summary (>80% coverage)
+- [ ] 8.2 Write unit tests for `TierService` — tier status, upgrade initiation, tier limit enforcement
+- [ ] 8.3 Write unit tests for `ComplianceService` — report generation, agent card export, cache hit/miss
+- [ ] 8.4 Write integration tests for all analytics endpoints (`/api/analytics/*`)
+- [ ] 8.5 Write integration tests for all tier endpoints (`/api/tiers/*`) including Stripe webhook
+- [ ] 8.6 Write integration tests for compliance endpoints (`/api/compliance/*`) including feature flag behavior
+- [ ] 8.7 Run full test suite — verify >80% coverage on all new services
+- [ ] 8.8 Run `tsc --noEmit` across API, portal, and CLI — zero errors
+- [ ] 8.9 Run `next build` for portal — verify clean build and code-split chunks
+- [ ] 8.10 Verify feature flags: `ANALYTICS_ENABLED=false` → 404 on analytics routes; `TIER_ENFORCEMENT=false` → no 429s; `COMPLIANCE_ENABLED=false` → 404 on compliance routes
+- [ ] 8.11 Run AGNTCY conformance suite — all tests pass
+- [ ] 8.12 Commit Phase 6 with message `feat(phase-6): WS3+WS4+WS6 — Analytics, Tiers, AGNTCY Compliance`