chore(openspec): archive phase-4-developer-growth change

All 90 tasks complete. Phase 4 — Developer Growth & Go-to-Market
fully delivered and archived per OpenSpec protocol.

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

openspec/changes/archive/2026-04-02-phase-4-developer-growth/specs/monitoring/spec.md

@@ -0,0 +1,29 @@
+## ADDED Requirements
+
+### Requirement: Rate limiter hit counter is exposed as Prometheus metric
+The system SHALL expose a `agentidp_rate_limit_hits_total` counter (labels: `endpoint`, `tenant_id`) incremented each time a request is rejected by the Redis-backed rate limiter (HTTP 429). This metric SHALL be available at `GET /metrics` alongside existing metrics.
+
+#### Scenario: Rate limit rejection increments counter
+- **WHEN** a client is rejected by the rate limiter on `POST /oauth2/token`
+- **THEN** `agentidp_rate_limit_hits_total{endpoint="/oauth2/token"}` is incremented by 1
+
+### Requirement: Database connection pool saturation is exposed as Prometheus metric
+The system SHALL expose `agentidp_db_pool_active_connections` (gauge) and `agentidp_db_pool_waiting_requests` (gauge) reflecting the current number of active database connections and queued requests waiting for a free connection.
+
+#### Scenario: Pool metrics reflect current state
+- **WHEN** 15 of 20 pool connections are in use and 2 requests are queued
+- **THEN** `agentidp_db_pool_active_connections` reads 15 and `agentidp_db_pool_waiting_requests` reads 2
+
+### Requirement: Per-tenant API call rate is exposed as Prometheus metric
+The system SHALL expose `agentidp_tenant_api_calls_total` counter (label: `tenant_id`) incremented on every authenticated API request. This enables per-tenant traffic analysis in Grafana.
+
+#### Scenario: Per-tenant counter increments on authenticated request
+- **WHEN** tenant `org-abc` makes an authenticated API call
+- **THEN** `agentidp_tenant_api_calls_total{tenant_id="org-abc"}` is incremented by 1
+
+### Requirement: Usage tier enforcement rejections are tracked as Prometheus metric
+The system SHALL expose `agentidp_billing_limit_rejections_total` counter (labels: `tenant_id`, `limit_type`) incremented each time a request is rejected due to a free tier limit (`agents` or `api_calls`).
+
+#### Scenario: Agent limit rejection increments counter
+- **WHEN** a free-tier tenant is rejected from creating an agent due to the 10-agent limit
+- **THEN** `agentidp_billing_limit_rejections_total{limit_type="agents"}` is incremented by 1