@thinkai/tai-api-contract 2.62.0 → 2.64.0

package/openapi/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: ThinkAI API
-  version: 2.62.0
+  version: 2.64.0
   description: >
     Contract surface for the AI Driven SDLC backend used by ThinkAI.
     Workspace-scoped routes use `/workspaces/{workspaceId}/...`.
@@ -54,6 +54,14 @@ tags:
     description: Agentic Foundation pillars (epic #278); reads stored repository readiness snapshots
   - name: YourAiJourney
     description: Your AI Journey dashboard aggregators (epic #267); composes readiness, metrics, and AI-spend data for the /dashboard page
+  - name: SdlcInsights
+    description: SDLC Engineering Health insights — DORA, CI, collaboration, security, governance, and operational metrics for `/insights/sdlc/overview`.
+  - name: InsightsRecommendations
+    description: >
+      Cross-analysis Insights & Recommendations page (`/insights-recommendations`).
+      Seven workspace-scoped GET resources under `/insights/recommendations-page/*`
+      with shared date/org/provider filters. Numbers are computed from dashboard metrics,
+      AI-tool usage/spend, org chart, and readiness — never mock payloads.
   - name: WorkspaceActivity
     description: Workspace-wide lifecycle activity log — repo add/remove/re-add and integration lifecycle events (issue #515).
   - name: PlatformAdmin
@@ -2610,6 +2618,412 @@ paths:
         "404":
           description: Workspace does not exist or malformed workspaceId
 
+  /workspaces/{workspaceId}/insights/sdlc/overview:
+    get:
+      tags: [SdlcInsights]
+      summary: SDLC insights — Engineering Health overview
+      description: >
+        Engineering Health dashboard for `/insights/sdlc/overview`. Returns precomputed
+        DORA, CI, collaboration, security, governance, and operational metrics aggregated
+        at calendar-day granularity for the selected window. Filter params mirror other
+        Measure insights routes plus optional `repoIds` scope.
+      operationId: getSdlcInsightsOverview
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - $ref: "#/components/parameters/InsightsSdlcRangeId"
+        - $ref: "#/components/parameters/InsightsDepartmentFilter"
+        - name: team
+          in: query
+          description: Team name filter; send `All teams` to include every team.
+          schema:
+            type: string
+            default: All teams
+        - name: repoIds
+          in: query
+          description: Comma-separated internal repo ids; omit or empty for all repos.
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Engineering Health overview payload
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SdlcOverviewDto"
+        "400":
+          description: Invalid query parameters
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [error]
+                properties:
+                  error: { type: string, example: invalid_query }
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist or malformed workspaceId
+
+  /workspaces/{workspaceId}/insights/sdlc/drilldown/{metricId}:
+    get:
+      tags: [SdlcInsights]
+      summary: SDLC insights — metric drill-down entities
+      description: >
+        Paginated entity list for a single Engineering Health metric (failed workflow runs,
+        PRs, alerts, etc.). Available only when the overview marks `drilldownAvailable: true`.
+      operationId: getSdlcInsightsDrilldown
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - name: metricId
+          in: path
+          required: true
+          schema:
+            $ref: "#/components/schemas/SdlcMetricId"
+        - $ref: "#/components/parameters/InsightsSdlcRangeId"
+        - $ref: "#/components/parameters/InsightsDepartmentFilter"
+        - name: team
+          in: query
+          schema:
+            type: string
+            default: All teams
+        - name: repoIds
+          in: query
+          schema:
+            type: string
+        - name: cursor
+          in: query
+          description: Opaque pagination cursor from a prior response.
+          schema:
+            type: string
+        - name: limit
+          in: query
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 100
+            default: 25
+      responses:
+        "200":
+          description: Drill-down page
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SdlcDrilldownDto"
+        "400":
+          description: Invalid query parameters
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [error]
+                properties:
+                  error: { type: string, example: invalid_query }
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace or metric not found
+
+  /workspaces/{workspaceId}/insights/recommendations-page/verdict-summary:
+    get:
+      tags: [InsightsRecommendations]
+      summary: Insights recommendations — verdict summary cards
+      description: >
+        Top status cards for `/insights-recommendations`. `productivityMultiplier` is the
+        merged-PR volume ratio versus the previous equal-length window (not AI-active vs
+        non-users). `ciFailRatePct` is portfolio CI fail rate percent. Cost statuses compare
+        AI spend per merged PR to the prior window. Status thresholds match the product UI:
+        productivity ≥1.5 healthy / ≥1.0 watch / else at-risk; CI fail <15 healthy / ≤30 watch /
+        else at-risk; cost change ≤0 healthy / <20% watch / else at-risk (prev≤0 → watch).
+      operationId: getInsightsRecommendationsVerdictSummary
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - $ref: "#/components/parameters/InsightsRecommendationsDepartments"
+        - $ref: "#/components/parameters/InsightsRecommendationsTeams"
+        - $ref: "#/components/parameters/InsightsRecommendationsDateFrom"
+        - $ref: "#/components/parameters/InsightsRecommendationsDateTo"
+        - $ref: "#/components/parameters/InsightsRecommendationsProvider"
+        - $ref: "#/components/parameters/InsightsRecommendationsIncludeUnmapped"
+        - $ref: "#/components/parameters/InsightsRecommendationsIncludeBots"
+      responses:
+        "200":
+          description: Verdict summary with `_meta.isMock=false`
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/InsightsRecommendationsVerdictSummaryResponse"
+        "400":
+          description: Invalid filter or date range
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [error]
+                properties:
+                  error: { type: string, example: invalid_query }
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist or malformed workspaceId
+
+  /workspaces/{workspaceId}/insights/recommendations-page/roi-quadrant:
+    get:
+      tags: [InsightsRecommendations]
+      summary: Insights recommendations — AI spend vs delivery output
+      description: >
+        Per-engineer AI spend (USD) and merged PR counts for the scatter / ROI quadrant.
+        Includes engineers with spend>0 or mergedPrs>0. Medians are over the returned set
+        (n<2 uses the single point or zeros when empty). `id` is the stable org person id.
+      operationId: getInsightsRecommendationsRoiQuadrant
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - $ref: "#/components/parameters/InsightsRecommendationsDepartments"
+        - $ref: "#/components/parameters/InsightsRecommendationsTeams"
+        - $ref: "#/components/parameters/InsightsRecommendationsDateFrom"
+        - $ref: "#/components/parameters/InsightsRecommendationsDateTo"
+        - $ref: "#/components/parameters/InsightsRecommendationsProvider"
+        - $ref: "#/components/parameters/InsightsRecommendationsIncludeUnmapped"
+        - $ref: "#/components/parameters/InsightsRecommendationsIncludeBots"
+      responses:
+        "200":
+          description: ROI quadrant payload
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/InsightsRecommendationsRoiQuadrantResponse"
+        "400":
+          description: Invalid filter or date range
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [error]
+                properties:
+                  error: { type: string, example: invalid_query }
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist or malformed workspaceId
+
+  /workspaces/{workspaceId}/insights/recommendations-page/velocity-quality:
+    get:
+      tags: [InsightsRecommendations]
+      summary: Insights recommendations — velocity vs quality weekly series
+      description: >
+        Weekly merged PR volume and CI fail rate for the filter window. Weeks follow the
+        Measure calendar-week bucket convention. `targetFailRatePct` is the org target (15).
+        `volumeGrowthPct` is percent change vs the prior equal-length period.
+      operationId: getInsightsRecommendationsVelocityQuality
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - $ref: "#/components/parameters/InsightsRecommendationsDepartments"
+        - $ref: "#/components/parameters/InsightsRecommendationsTeams"
+        - $ref: "#/components/parameters/InsightsRecommendationsDateFrom"
+        - $ref: "#/components/parameters/InsightsRecommendationsDateTo"
+        - $ref: "#/components/parameters/InsightsRecommendationsProvider"
+        - $ref: "#/components/parameters/InsightsRecommendationsIncludeUnmapped"
+        - $ref: "#/components/parameters/InsightsRecommendationsIncludeBots"
+      responses:
+        "200":
+          description: Velocity vs quality payload
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/InsightsRecommendationsVelocityQualityResponse"
+        "400":
+          description: Invalid filter or date range
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [error]
+                properties:
+                  error: { type: string, example: invalid_query }
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist or malformed workspaceId
+
+  /workspaces/{workspaceId}/insights/recommendations-page/review-pipeline:
+    get:
+      tags: [InsightsRecommendations]
+      summary: Insights recommendations — review bottleneck funnel
+      description: >
+        Review funnel stages `open-review`, `review-approval`, `approval-merge`, and `merged`.
+        Wait stages use delivery-health hours (`avgReviewWaitHours`, `avgApprovalHours`, and
+        approval→merge as max(0, avgTimeToMergeHours − wait − approval)). The `merged` stage
+        uses `medianHours=0` (volume is not hours). `bottleneckStageId` is the wait stage with
+        the highest median hours. `reviewerLoad` comes from persisted `deliveryHealth.topReviewers`
+        when available; otherwise an empty array (never invented reviewers).
+      operationId: getInsightsRecommendationsReviewPipeline
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - $ref: "#/components/parameters/InsightsRecommendationsDepartments"
+        - $ref: "#/components/parameters/InsightsRecommendationsTeams"
+        - $ref: "#/components/parameters/InsightsRecommendationsDateFrom"
+        - $ref: "#/components/parameters/InsightsRecommendationsDateTo"
+        - $ref: "#/components/parameters/InsightsRecommendationsProvider"
+        - $ref: "#/components/parameters/InsightsRecommendationsIncludeUnmapped"
+        - $ref: "#/components/parameters/InsightsRecommendationsIncludeBots"
+      responses:
+        "200":
+          description: Review pipeline payload
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/InsightsRecommendationsReviewPipelineResponse"
+        "400":
+          description: Invalid filter or date range
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [error]
+                properties:
+                  error: { type: string, example: invalid_query }
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist or malformed workspaceId
+
+  /workspaces/{workspaceId}/insights/recommendations-page/cost-per-pr:
+    get:
+      tags: [InsightsRecommendations]
+      summary: Insights recommendations — cost per merged PR by team
+      description: >
+        Org and per-team AI spend / merged PRs. Teams with zero merged PRs in the window are
+        omitted. `costPerPrUsd = spendUsd / mergedPrs`. `activeAi` is distinct AI-active members
+        on the team in the window (provider filter applied).
+      operationId: getInsightsRecommendationsCostPerPr
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - $ref: "#/components/parameters/InsightsRecommendationsDepartments"
+        - $ref: "#/components/parameters/InsightsRecommendationsTeams"
+        - $ref: "#/components/parameters/InsightsRecommendationsDateFrom"
+        - $ref: "#/components/parameters/InsightsRecommendationsDateTo"
+        - $ref: "#/components/parameters/InsightsRecommendationsProvider"
+        - $ref: "#/components/parameters/InsightsRecommendationsIncludeUnmapped"
+        - $ref: "#/components/parameters/InsightsRecommendationsIncludeBots"
+      responses:
+        "200":
+          description: Cost per PR payload
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/InsightsRecommendationsCostPerPrResponse"
+        "400":
+          description: Invalid filter or date range
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [error]
+                properties:
+                  error: { type: string, example: invalid_query }
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist or malformed workspaceId
+
+  /workspaces/{workspaceId}/insights/recommendations-page/adoption-gap:
+    get:
+      tags: [InsightsRecommendations]
+      summary: Insights recommendations — AI adoption gap by team
+      description: >
+        Headcount vs AI-active contributors and per-team readiness/output. `readinessPct` is the
+        mean latest overallScore of repos with matching `teamId` (workspace mean fallback).
+        `outputPerEngPerWeek` is team merged PRs / headcount / weeks in window. `upliftPct`
+        estimates additional PR volume if non-adopters matched leader-team output
+        (teams with >50% adoption).
+      operationId: getInsightsRecommendationsAdoptionGap
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - $ref: "#/components/parameters/InsightsRecommendationsDepartments"
+        - $ref: "#/components/parameters/InsightsRecommendationsTeams"
+        - $ref: "#/components/parameters/InsightsRecommendationsDateFrom"
+        - $ref: "#/components/parameters/InsightsRecommendationsDateTo"
+        - $ref: "#/components/parameters/InsightsRecommendationsProvider"
+        - $ref: "#/components/parameters/InsightsRecommendationsIncludeUnmapped"
+        - $ref: "#/components/parameters/InsightsRecommendationsIncludeBots"
+      responses:
+        "200":
+          description: Adoption gap payload
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/InsightsRecommendationsAdoptionGapResponse"
+        "400":
+          description: Invalid filter or date range
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [error]
+                properties:
+                  error: { type: string, example: invalid_query }
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist or malformed workspaceId
+
+  /workspaces/{workspaceId}/insights/recommendations-page/recommendations:
+    get:
+      tags: [InsightsRecommendations]
+      summary: Insights recommendations — deterministic action items
+      description: >
+        Deterministic rules engine (no LLM). Emits module-anchored recommendations with
+        `moduleId` in {mod-spend-vs-output, mod-velocity-vs-quality, mod-review-bottleneck,
+        mod-cost-per-pr, mod-adoption-gap}. Action items must cite one AI metric and one
+        delivery metric in `observed`. Evidence chips use kinds user-spend|team|contributor|repo|module
+        with real target ids when available.
+      operationId: getInsightsRecommendationsRecommendations
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - $ref: "#/components/parameters/InsightsRecommendationsDepartments"
+        - $ref: "#/components/parameters/InsightsRecommendationsTeams"
+        - $ref: "#/components/parameters/InsightsRecommendationsDateFrom"
+        - $ref: "#/components/parameters/InsightsRecommendationsDateTo"
+        - $ref: "#/components/parameters/InsightsRecommendationsProvider"
+        - $ref: "#/components/parameters/InsightsRecommendationsIncludeUnmapped"
+        - $ref: "#/components/parameters/InsightsRecommendationsIncludeBots"
+      responses:
+        "200":
+          description: Recommendation items
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/InsightsRecommendationsListResponse"
+        "400":
+          description: Invalid filter or date range
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [error]
+                properties:
+                  error: { type: string, example: invalid_query }
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist or malformed workspaceId
+
   /workspaces/{workspaceId}/integrations/ai-tool/{provider}/members:
     get:
       tags: [Workspace]
@@ -7071,32 +7485,107 @@ components:
       name: from
       in: query
       description: >
-        Inclusive start of a daily window (`YYYY-MM-DD`). When set with `to`, overrides `rangeId`
-        for day-mode responses (max 180 days).
+        Inclusive start of a daily window (`YYYY-MM-DD`). When set with `to`, overrides `rangeId`
+        for day-mode responses (max 180 days).
+      schema:
+        type: string
+        format: date
+    InsightsProductivityTo:
+      name: to
+      in: query
+      description: >
+        Inclusive end of a daily window (`YYYY-MM-DD`). When set with `from`, overrides `rangeId`
+        for day-mode responses (max 180 days).
+      schema:
+        type: string
+        format: date
+    InsightsSdlcRangeId:
+      name: rangeId
+      in: query
+      description: >
+        Day-level Measure window. Presets: `7d`, `30d`, `90d`, `180d`. Custom inclusive
+        calendar range: `cr:YYYY-MM-DD:YYYY-MM-DD` (max span 180 days).
+      schema:
+        type: string
+        default: 30d
+        example: 30d
+    InsightsDepartmentFilter:
+      name: department
+      in: query
+      description: >
+        Department filter; send `All departments` to include every department. Scoped using
+        imported `thinkai_org_structure` members when present, otherwise SPA org chart
+        `department` nodes and their descendant teams. When neither source defines the
+        requested department, insights return no scoped teams or contributors (not org-wide
+        data).
+      schema:
+        type: string
+        default: All departments
+    InsightsRecommendationsDepartments:
+      name: departments
+      in: query
+      description: >
+        Org-chart department ids (repeat param or comma-separated). Empty/omitted = all departments.
+      schema:
+        type: array
+        items:
+          type: string
+      style: form
+      explode: true
+    InsightsRecommendationsTeams:
+      name: teams
+      in: query
+      description: >
+        Org-chart team ids (repeat param or comma-separated). Empty/omitted = all teams in department scope.
+      schema:
+        type: array
+        items:
+          type: string
+      style: form
+      explode: true
+    InsightsRecommendationsDateFrom:
+      name: dateFrom
+      in: query
+      description: >
+        Inclusive window start (`YYYY-MM-DD`). Required with `dateTo`. Maps to Measure day-mode
+        custom range (`from`/`to`). Max span 180 days.
+      required: true
       schema:
         type: string
         format: date
-    InsightsProductivityTo:
-      name: to
+    InsightsRecommendationsDateTo:
+      name: dateTo
       in: query
-      description: >
-        Inclusive end of a daily window (`YYYY-MM-DD`). When set with `from`, overrides `rangeId`
-        for day-mode responses (max 180 days).
+      description: Inclusive window end (`YYYY-MM-DD`). Required with `dateFrom`.
+      required: true
       schema:
         type: string
         format: date
-    InsightsDepartmentFilter:
-      name: department
+    InsightsRecommendationsProvider:
+      name: provider
       in: query
       description: >
-        Department filter; send `All departments` to include every department. Scoped using
-        imported `thinkai_org_structure` members when present, otherwise SPA org chart
-        `department` nodes and their descendant teams. When neither source defines the
-        requested department, insights return no scoped teams or contributors (not org-wide
-        data).
+        AI provider ids (e.g. `cursor`, `copilot`). Empty/omitted = all configured providers.
       schema:
-        type: string
-        default: All departments
+        type: array
+        items:
+          type: string
+      style: form
+      explode: true
+    InsightsRecommendationsIncludeUnmapped:
+      name: includeUnmapped
+      in: query
+      description: Include contributors / AI rows not mapped to a team.
+      schema:
+        type: boolean
+        default: true
+    InsightsRecommendationsIncludeBots:
+      name: includeBots
+      in: query
+      description: Include bot accounts in PR/CI stats.
+      schema:
+        type: boolean
+        default: false
     PaginationLimit:
       name: limit
       in: query
@@ -14185,3 +14674,514 @@ components:
           type: string
           format: date-time
           description: Timestamp of the most recent contributing run (UTC).
+
+    SdlcModuleId:
+      type: string
+      enum:
+        - dora
+        - ci-pipeline
+        - collaboration-pr
+        - security-risk
+        - governance-architecture
+        - financial-operational
+
+    SdlcMetricId:
+      type: string
+      enum:
+        - dora-deployment-frequency
+        - dora-lead-time
+        - dora-cfr
+        - dora-mttr
+        - ci-success-rate
+        - ci-duration-p50-p95
+        - ci-flakiness
+        - ci-queue-wait
+        - ci-cache-hit
+        - pr-review-time
+        - pr-bus-factor
+        - pr-size
+        - pr-abandonment
+        - pr-review-depth
+        - pr-draft-duration
+        - pr-merge-conflicts
+        - pr-commit-density
+        - sec-dependabot-backlog
+        - sec-vuln-mttr
+        - sec-secret-scanning
+        - sec-self-approvals
+        - sec-unreviewed-merge
+        - gov-branch-protection
+        - gov-stale-branches
+        - gov-orphaned-repos
+        - gov-readme-health
+        - gov-codeowners
+        - gov-issue-pr-linkage
+        - fin-gha-minutes
+        - fin-copilot-utilization
+        - fin-org-inactivity
+        - fin-env-drift
+        - fin-release-cadence
+        - fin-api-rate-limit
+
+    SdlcMetricDataStatus:
+      type: string
+      enum: [live, preview, unavailable]
+
+    SdlcMetricHealthStatus:
+      type: string
+      enum: [healthy, warning, critical, unknown]
+
+    SdlcBenchmarkBand:
+      type: string
+      enum: [elite, high, medium, low]
+
+    SdlcMetricTrendDto:
+      type: object
+      required: [direction]
+      properties:
+        direction:
+          type: string
+          enum: [up, down, flat]
+        deltaPercent:
+          type: number
+
+    SdlcDailySeriesPointDto:
+      type: object
+      required: [date, value]
+      properties:
+        date:
+          type: string
+          format: date
+          description: Inclusive ISO calendar day (UTC).
+        value:
+          type: number
+
+    SdlcMetricDto:
+      type: object
+      required: [id, name, dataStatus, healthStatus, value, drilldownAvailable]
+      properties:
+        id:
+          $ref: "#/components/schemas/SdlcMetricId"
+        name:
+          type: string
+        dataStatus:
+          $ref: "#/components/schemas/SdlcMetricDataStatus"
+        healthStatus:
+          $ref: "#/components/schemas/SdlcMetricHealthStatus"
+        value:
+          oneOf:
+            - type: number
+            - type: string
+          nullable: true
+        unit:
+          type: string
+        secondaryValue:
+          oneOf:
+            - type: number
+            - type: string
+          nullable: true
+        secondaryLabel:
+          type: string
+        trend:
+          $ref: "#/components/schemas/SdlcMetricTrendDto"
+        benchmarkBand:
+          $ref: "#/components/schemas/SdlcBenchmarkBand"
+        drilldownAvailable:
+          type: boolean
+        dailySeries:
+          type: array
+          items:
+            $ref: "#/components/schemas/SdlcDailySeriesPointDto"
+        unavailableReason:
+          type: string
+
+    SdlcModuleDto:
+      type: object
+      required: [id, name, metrics]
+      properties:
+        id:
+          $ref: "#/components/schemas/SdlcModuleId"
+        name:
+          type: string
+        metrics:
+          type: array
+          items:
+            $ref: "#/components/schemas/SdlcMetricDto"
+
+    SdlcOverviewDto:
+      type: object
+      required: [rangeId, from, to, department, team, repoIds, asOf, modules]
+      properties:
+        rangeId:
+          type: string
+        from:
+          type: string
+          format: date
+        to:
+          type: string
+          format: date
+        department:
+          type: string
+        team:
+          type: string
+        repoIds:
+          type: array
+          items:
+            type: string
+        asOf:
+          type: string
+          format: date-time
+        modules:
+          type: array
+          items:
+            $ref: "#/components/schemas/SdlcModuleDto"
+
+    SdlcDrilldownItemDto:
+      type: object
+      required: [id, title]
+      properties:
+        id:
+          type: string
+        title:
+          type: string
+        subtitle:
+          type: string
+        url:
+          type: string
+          format: uri
+        occurredAt:
+          type: string
+          format: date-time
+        metadata:
+          type: object
+          additionalProperties:
+            oneOf:
+              - type: string
+              - type: number
+
+    SdlcDrilldownDto:
+      type: object
+      required: [metricId, items]
+      properties:
+        metricId:
+          $ref: "#/components/schemas/SdlcMetricId"
+        items:
+          type: array
+          items:
+            $ref: "#/components/schemas/SdlcDrilldownItemDto"
+        nextCursor:
+          type: string
+
+    InsightsResponseMeta:
+      type: object
+      required: [syncedAt, isMock]
+      properties:
+        syncedAt:
+          type: string
+          format: date-time
+          description: ISO timestamp when numbers were computed server-side
+        isMock:
+          type: boolean
+          description: Must be false for production handlers
+          enum: [false]
+
+    InsightsVerdictStatus:
+      type: string
+      enum: [healthy, watch, at-risk]
+
+    InsightsRecommendationsVerdictSummary:
+      type: object
+      required:
+        - productivityMultiplier
+        - productivityStatus
+        - ciFailRatePct
+        - qualityStatus
+        - spendPerMergedPrUsd
+        - spendPerMergedPrPrevUsd
+        - costStatus
+      properties:
+        productivityMultiplier:
+          type: number
+          description: >
+            Merged-PR volume ratio vs prior equal-length window (current/prior).
+            When priorMergedPrs is 0, value is 1.0 and productivityStatus is watch.
+        productivityStatus:
+          $ref: "#/components/schemas/InsightsVerdictStatus"
+        ciFailRatePct:
+          type: number
+        qualityStatus:
+          $ref: "#/components/schemas/InsightsVerdictStatus"
+        spendPerMergedPrUsd:
+          type: number
+        spendPerMergedPrPrevUsd:
+          type: number
+        costStatus:
+          $ref: "#/components/schemas/InsightsVerdictStatus"
+
+    InsightsRecommendationsVerdictSummaryResponse:
+      allOf:
+        - $ref: "#/components/schemas/InsightsRecommendationsVerdictSummary"
+        - type: object
+          required: [_meta]
+          properties:
+            _meta:
+              $ref: "#/components/schemas/InsightsResponseMeta"
+
+    InsightsRoiEngineerPoint:
+      type: object
+      required: [id, name, team, spendUsd, mergedPrs]
+      properties:
+        id: { type: string }
+        name: { type: string }
+        team: { type: string }
+        spendUsd: { type: number }
+        mergedPrs: { type: number }
+
+    InsightsRecommendationsRoiQuadrant:
+      type: object
+      required: [medianSpendUsd, medianMergedPrs, engineers, correlationHint]
+      properties:
+        medianSpendUsd: { type: number }
+        medianMergedPrs: { type: number }
+        engineers:
+          type: array
+          items:
+            $ref: "#/components/schemas/InsightsRoiEngineerPoint"
+        correlationHint: { type: string }
+
+    InsightsRecommendationsRoiQuadrantResponse:
+      allOf:
+        - $ref: "#/components/schemas/InsightsRecommendationsRoiQuadrant"
+        - type: object
+          required: [_meta]
+          properties:
+            _meta:
+              $ref: "#/components/schemas/InsightsResponseMeta"
+
+    InsightsVelocityQualityWeek:
+      type: object
+      required: [weekStartIso, mergedPrs, ciFailRatePct]
+      properties:
+        weekStartIso: { type: string, format: date }
+        mergedPrs: { type: number }
+        ciFailRatePct: { type: number }
+
+    InsightsRecommendationsVelocityQuality:
+      type: object
+      required: [weeks, targetFailRatePct, volumeGrowthPct]
+      properties:
+        weeks:
+          type: array
+          items:
+            $ref: "#/components/schemas/InsightsVelocityQualityWeek"
+        targetFailRatePct: { type: number }
+        volumeGrowthPct: { type: number }
+
+    InsightsRecommendationsVelocityQualityResponse:
+      allOf:
+        - $ref: "#/components/schemas/InsightsRecommendationsVelocityQuality"
+        - type: object
+          required: [_meta]
+          properties:
+            _meta:
+              $ref: "#/components/schemas/InsightsResponseMeta"
+
+    InsightsReviewStageId:
+      type: string
+      enum: [open-review, review-approval, approval-merge, merged]
+
+    InsightsReviewStage:
+      type: object
+      required: [id, name, medianHours, trendPct]
+      properties:
+        id:
+          $ref: "#/components/schemas/InsightsReviewStageId"
+        name: { type: string }
+        medianHours:
+          type: number
+          description: Wait hours for funnel stages; 0 for the merged volume stage
+        trendPct: { type: number }
+
+    InsightsReviewerLoadItem:
+      type: object
+      required: [id, name, reviewsCount, sharePct]
+      properties:
+        id: { type: string }
+        name: { type: string }
+        reviewsCount: { type: number }
+        sharePct: { type: number }
+
+    InsightsRecommendationsReviewPipeline:
+      type: object
+      required: [stages, bottleneckStageId, reviewerLoad]
+      properties:
+        stages:
+          type: array
+          items:
+            $ref: "#/components/schemas/InsightsReviewStage"
+        bottleneckStageId:
+          $ref: "#/components/schemas/InsightsReviewStageId"
+        reviewerLoad:
+          type: array
+          items:
+            $ref: "#/components/schemas/InsightsReviewerLoadItem"
+
+    InsightsRecommendationsReviewPipelineResponse:
+      allOf:
+        - $ref: "#/components/schemas/InsightsRecommendationsReviewPipeline"
+        - type: object
+          required: [_meta]
+          properties:
+            _meta:
+              $ref: "#/components/schemas/InsightsResponseMeta"
+
+    InsightsCostPerPrTeam:
+      type: object
+      required: [id, name, activeAi, spendUsd, mergedPrs, costPerPrUsd, changePct]
+      properties:
+        id: { type: string }
+        name: { type: string }
+        activeAi: { type: number }
+        spendUsd: { type: number }
+        mergedPrs: { type: number }
+        costPerPrUsd: { type: number }
+        changePct: { type: number }
+
+    InsightsRecommendationsCostPerPr:
+      type: object
+      required: [orgAvgCostUsd, orgAvgPrevUsd, teams]
+      properties:
+        orgAvgCostUsd: { type: number }
+        orgAvgPrevUsd: { type: number }
+        teams:
+          type: array
+          items:
+            $ref: "#/components/schemas/InsightsCostPerPrTeam"
+
+    InsightsRecommendationsCostPerPrResponse:
+      allOf:
+        - $ref: "#/components/schemas/InsightsRecommendationsCostPerPr"
+        - type: object
+          required: [_meta]
+          properties:
+            _meta:
+              $ref: "#/components/schemas/InsightsResponseMeta"
+
+    InsightsAdoptionTeam:
+      type: object
+      required: [id, name, activeAi, totalMembers, readinessPct, outputPerEngPerWeek]
+      properties:
+        id: { type: string }
+        name: { type: string }
+        activeAi: { type: number }
+        totalMembers: { type: number }
+        readinessPct: { type: number }
+        outputPerEngPerWeek: { type: number }
+
+    InsightsRecommendationsAdoptionGap:
+      type: object
+      required: [totalContributors, activeContributors, upliftPct, teams]
+      properties:
+        totalContributors: { type: number }
+        activeContributors: { type: number }
+        upliftPct: { type: number }
+        teams:
+          type: array
+          items:
+            $ref: "#/components/schemas/InsightsAdoptionTeam"
+
+    InsightsRecommendationsAdoptionGapResponse:
+      allOf:
+        - $ref: "#/components/schemas/InsightsRecommendationsAdoptionGap"
+        - type: object
+          required: [_meta]
+          properties:
+            _meta:
+              $ref: "#/components/schemas/InsightsResponseMeta"
+
+    InsightsRecommendationModuleId:
+      type: string
+      enum:
+        - mod-spend-vs-output
+        - mod-velocity-vs-quality
+        - mod-review-bottleneck
+        - mod-cost-per-pr
+        - mod-adoption-gap
+
+    InsightsRecommendationImpact:
+      type: string
+      enum: [high, medium]
+
+    InsightsRecommendationTone:
+      type: string
+      enum: [action, no-action]
+
+    InsightsEvidenceLinkKind:
+      type: string
+      enum: [user-spend, team, contributor, repo, module]
+
+    InsightsEvidenceChip:
+      type: object
+      required: [label, kind, targetId]
+      properties:
+        label: { type: string }
+        kind:
+          $ref: "#/components/schemas/InsightsEvidenceLinkKind"
+        targetId: { type: string }
+
+    InsightsRecommendationEvidenceGroup:
+      type: object
+      required: [title, chips]
+      properties:
+        title: { type: string }
+        chips:
+          type: array
+          items:
+            $ref: "#/components/schemas/InsightsEvidenceChip"
+
+    InsightsRecommendationDto:
+      type: object
+      required:
+        - moduleId
+        - moduleName
+        - tone
+        - impact
+        - headline
+        - observed
+        - action
+        - benefit
+        - confidencePct
+        - evidence
+      properties:
+        moduleId:
+          $ref: "#/components/schemas/InsightsRecommendationModuleId"
+        moduleName: { type: string }
+        tone:
+          $ref: "#/components/schemas/InsightsRecommendationTone"
+        impact:
+          $ref: "#/components/schemas/InsightsRecommendationImpact"
+        headline: { type: string }
+        observed:
+          type: string
+          description: For tone=action must cite one AI metric and one delivery metric
+        action: { type: string }
+        benefit: { type: string }
+        confidencePct:
+          type: number
+          minimum: 0
+          maximum: 100
+        evidence:
+          type: array
+          items:
+            $ref: "#/components/schemas/InsightsRecommendationEvidenceGroup"
+
+    InsightsRecommendationsListResponse:
+      type: object
+      required: [items, _meta]
+      properties:
+        items:
+          type: array
+          items:
+            $ref: "#/components/schemas/InsightsRecommendationDto"
+        _meta:
+          $ref: "#/components/schemas/InsightsResponseMeta"