@thinkai/tai-api-contract 2.125.0 → 2.127.0

package/openapi/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: ThinkAI API
-  version: 2.125.0
+  version: 2.127.0
   description: >
     Contract surface for the AI Driven SDLC backend used by ThinkAI.
     Workspace-scoped routes use `/workspaces/{workspaceId}/...`.
@@ -86,6 +86,12 @@ tags:
       (LOC, cyclomatic complexity, duplication), hotspots, and playbook-threshold
       findings collected during readiness scans. Every metric carries
       `measured | derived | estimated | unavailable` provenance.
+  - name: TestPyramidInsights
+    description: >
+      Test pyramid assessment (`/insights/test-pyramid`) — workspace and per-repo
+      classified test-file inventory (unit, integration, acceptance/BDD, contract, E2E)
+      with count-based presence and advisory 70/20/10 shape. Distinct from Agentic
+      Foundation readiness `/readiness/test-pyramid*` (signal-inclusive presence).
 
 paths:
   /admin/users/{userId}:
@@ -3831,6 +3837,84 @@ paths:
               schema:
                 $ref: "#/components/schemas/ErrorMessageDto"
 
+  /workspaces/{workspaceId}/insights/test-pyramid/summary:
+    get:
+      tags: [TestPyramidInsights]
+      summary: Test pyramid assessment — workspace summary
+      operationId: getInsightsTestPyramidSummary
+      description: >
+        Org-level Test pyramid assessment for `/insights/test-pyramid`. Aggregates each
+        active repo's **latest** readiness-scan test-pyramid snapshot. Layer **presence
+        is count-based** (`fileCount > 0`); CI/dependency-only AF `present` flags are
+        ignored. Shape uses fixed advisory targets (base ~70% unit, middle ~20%
+        integration+contract+acceptance/BDD, top ~10% E2E) and returns
+        `insufficient_data` when total classified test files < 10. Does not change
+        Agentic Foundation `/readiness/test-pyramid*` responses.
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Test pyramid assessment workspace summary
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/InsightsTestPyramidSummaryDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist or malformed workspaceId
+        "501":
+          description: Test pyramid history not supported by store
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
+  /workspaces/{workspaceId}/insights/test-pyramid/repos:
+    get:
+      tags: [TestPyramidInsights]
+      summary: Test pyramid assessment — per-repo list (paginated)
+      operationId: listInsightsTestPyramidRepos
+      description: >
+        Page of repos with latest classified test-file counts, count-based presence,
+        presence maturity, and shape assessment. Use `gapsByLayer` on the summary
+        endpoint (or filter this list via layerPresent) to answer “who lacks layer X?”.
+        No v1 repo-detail Insights route — link repo names to AF readiness inventory.
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - $ref: "#/components/parameters/PaginationLimit"
+        - $ref: "#/components/parameters/PaginationOffset"
+        - $ref: "#/components/parameters/InsightsTestPyramidRepoSort"
+        - $ref: "#/components/parameters/PaginationOrder"
+        - $ref: "#/components/parameters/InsightsTestPyramidRepoSearch"
+      responses:
+        "200":
+          description: Paginated test pyramid assessment repo rows
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/InsightsTestPyramidRepoListDto"
+        "400":
+          description: Invalid pagination or sort query
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist or malformed workspaceId
+        "501":
+          description: Test pyramid history not supported by store
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
   /workspaces/{workspaceId}/integrations/ai-tool/{provider}/members:
     get:
       tags: [Workspace]
@@ -6420,6 +6504,134 @@ paths:
               schema:
                 $ref: "#/components/schemas/ErrorMessageDto"
 
+  /workspaces/{workspaceId}/readiness/test-pyramid:
+    get:
+      tags: [RepositoryReadiness]
+      summary: Latest test-pyramid report and progress per repository
+      description: >
+        Returns the latest test inventory for every repository with a pyramid snapshot,
+        deltas from the previous and baseline scans, and workspace layer coverage.
+        Repositories whose historical runs predate pyramid snapshots are omitted.
+      operationId: getReadinessTestPyramid
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Latest test-pyramid report and progress
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/WorkspaceTestPyramidProgressDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "501":
+          description: Readiness history is not supported by the configured store
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
+  /workspaces/{workspaceId}/readiness/test-pyramid/history:
+    get:
+      tags: [RepositoryReadiness]
+      summary: Historical test-pyramid snapshots per repository
+      description: >
+        Returns succeeded readiness runs containing test-pyramid snapshots, ordered oldest
+        to newest per repository. Older runs without snapshots are omitted, not treated as gaps.
+      operationId: getReadinessTestPyramidHistory
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - name: since
+          in: query
+          schema:
+            type: string
+            format: date-time
+        - name: limitPerRepo
+          in: query
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 200
+            default: 50
+      responses:
+        "200":
+          description: Test-pyramid history grouped by repository
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/WorkspaceTestPyramidHistoryDto"
+        "400":
+          description: Invalid query
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "501":
+          description: Readiness history is not supported by the configured store
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
+  /workspaces/{workspaceId}/readiness/test-pyramid/progress:
+    get:
+      tags: [RepositoryReadiness]
+      summary: Test-pyramid code progress from successive scans
+      description: >
+        Compares each repository's latest pyramid snapshot with its previous and baseline
+        snapshots. Reports layer adoption/removal, file-count and Tests & QA score deltas,
+        criterion changes, and current workspace coverage.
+      operationId: getReadinessTestPyramidProgress
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - name: since
+          in: query
+          schema:
+            type: string
+            format: date-time
+        - name: limitPerRepo
+          in: query
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 200
+            default: 50
+      responses:
+        "200":
+          description: Test-pyramid code progress
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/WorkspaceTestPyramidProgressDto"
+        "400":
+          description: Invalid query
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "501":
+          description: Readiness history is not supported by the configured store
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
   /workspaces/{workspaceId}/readiness/score-history:
     get:
       tags: [RepositoryReadiness]
@@ -9923,6 +10135,23 @@ components:
       description: Case-insensitive substring filter on repo name / provider slug.
       schema:
         type: string
+    InsightsTestPyramidRepoSort:
+      name: sort
+      in: query
+      required: false
+      description: Allowlisted Test pyramid assessment repo sort field.
+      schema:
+        type: string
+        enum: [repoName, totalClassifiedFiles, scannedAt, maturity]
+        default: repoName
+    InsightsTestPyramidRepoSearch:
+      name: search
+      in: query
+      required: false
+      description: Case-insensitive substring filter on repository name.
+      schema:
+        type: string
+        maxLength: 256
     ReadinessRepoSearch:
       name: search
       in: query
@@ -15902,6 +16131,406 @@ components:
           maximum: 100
           description: Dimension score as a percentage (0–100) for this scan run.
 
+    TestPyramidLayerSnapshotDto:
+      type: object
+      required: [present, applicable, confidence, fileCount, frameworks, evidence]
+      properties:
+        present:
+          type: boolean
+        applicable:
+          type: boolean
+          description: False when the repository archetype makes this layer not applicable.
+        confidence:
+          type: string
+          enum: [high, medium, low]
+        fileCount:
+          type: integer
+          minimum: 0
+        frameworks:
+          type: array
+          items:
+            type: string
+        evidence:
+          type: array
+          maxItems: 8
+          items:
+            type: string
+          description: Capped relative file paths or script names supporting the classification.
+        lineCoverage:
+          $ref: "#/components/schemas/TestPyramidLineCoverageDto"
+
+    TestPyramidLayersDto:
+      type: object
+      required: [unit, integration, acceptance_bdd, contract, e2e]
+      properties:
+        unit:
+          $ref: "#/components/schemas/TestPyramidLayerSnapshotDto"
+        integration:
+          $ref: "#/components/schemas/TestPyramidLayerSnapshotDto"
+        acceptance_bdd:
+          $ref: "#/components/schemas/TestPyramidLayerSnapshotDto"
+        contract:
+          $ref: "#/components/schemas/TestPyramidLayerSnapshotDto"
+        e2e:
+          $ref: "#/components/schemas/TestPyramidLayerSnapshotDto"
+
+    TestPyramidSnapshotDto:
+      type: object
+      required: [version, layers, e2eCrossRepoCandidate, e2eReferencedTargets]
+      properties:
+        version:
+          type: integer
+          enum: [1]
+        layers:
+          $ref: "#/components/schemas/TestPyramidLayersDto"
+        e2eCrossRepoCandidate:
+          type: boolean
+          description: Evidence suggests the repository's E2E suite exercises multiple services.
+        e2eReferencedTargets:
+          type: array
+          maxItems: 20
+          items:
+            type: string
+          description: Hostnames or compose service names referenced by the E2E suite.
+        lineCoverage:
+          $ref: "#/components/schemas/TestPyramidLineCoverageDto"
+
+    TestPyramidLineCoverageDto:
+      type: object
+      nullable: true
+      required: [linePercent, branchPercent, source]
+      properties:
+        linePercent:
+          type: number
+          minimum: 0
+          maximum: 100
+          description: Line coverage percent from Sonar or a committed coverage report.
+        branchPercent:
+          type: number
+          minimum: 0
+          maximum: 100
+          nullable: true
+        source:
+          type: string
+          enum: [sonar, jacoco, lcov, cobertura, clover, go_cover]
+        reportPath:
+          type: string
+          nullable: true
+          description: Path of the scanned report when the source is not Sonar.
+
+    TestPyramidCriteriaDto:
+      type: object
+      properties:
+        D1:
+          type: string
+        D2:
+          type: string
+        D3:
+          type: string
+        D4:
+          type: string
+
+    TestPyramidRunStatusDto:
+      type: string
+      description: >-
+        Run state the snapshot came from. The pyramid is derived from the filesystem scan, which
+        finishes before rubric grading, so `partial_failed` and `failed` runs still carry a valid
+        snapshot but no scores.
+      enum: [succeeded, partial_failed, failed]
+
+    TestPyramidHistoryPointDto:
+      type: object
+      required:
+        [finishedAt, runStatus, overallScore, testsQaPercent, testPyramid, testPyramidCriteria]
+      properties:
+        finishedAt:
+          type: string
+          format: date-time
+        runStatus:
+          $ref: "#/components/schemas/TestPyramidRunStatusDto"
+        overallScore:
+          type: integer
+          minimum: 0
+          maximum: 100
+          nullable: true
+        testsQaPercent:
+          type: integer
+          minimum: 0
+          maximum: 100
+          nullable: true
+        testPyramid:
+          $ref: "#/components/schemas/TestPyramidSnapshotDto"
+        testPyramidCriteria:
+          $ref: "#/components/schemas/TestPyramidCriteriaDto"
+
+    TestPyramidRepoHistoryDto:
+      type: object
+      required: [repoId, repoName, connectedAt, points]
+      properties:
+        repoId:
+          type: string
+          format: uuid
+        repoName:
+          type: string
+        connectedAt:
+          type: string
+          format: date-time
+        points:
+          type: array
+          items:
+            $ref: "#/components/schemas/TestPyramidHistoryPointDto"
+
+    WorkspaceTestPyramidHistoryDto:
+      type: object
+      required: [workspaceId, generatedAt, repos]
+      properties:
+        workspaceId:
+          type: string
+          format: uuid
+        generatedAt:
+          type: string
+          format: date-time
+        repos:
+          type: array
+          items:
+            $ref: "#/components/schemas/TestPyramidRepoHistoryDto"
+
+    TestPyramidLayerDeltaDto:
+      type: object
+      required: [presence, fileCountDelta, addedFrameworks]
+      properties:
+        presence:
+          type: string
+          enum: [unchanged, adopted, removed]
+        fileCountDelta:
+          type: integer
+        addedFrameworks:
+          type: array
+          items:
+            type: string
+
+    TestPyramidLayerDeltasDto:
+      type: object
+      required: [unit, integration, acceptance_bdd, contract, e2e]
+      properties:
+        unit:
+          $ref: "#/components/schemas/TestPyramidLayerDeltaDto"
+        integration:
+          $ref: "#/components/schemas/TestPyramidLayerDeltaDto"
+        acceptance_bdd:
+          $ref: "#/components/schemas/TestPyramidLayerDeltaDto"
+        contract:
+          $ref: "#/components/schemas/TestPyramidLayerDeltaDto"
+        e2e:
+          $ref: "#/components/schemas/TestPyramidLayerDeltaDto"
+
+    TestPyramidCriterionDeltaDto:
+      type: object
+      required: [from, to]
+      properties:
+        from:
+          type: string
+          nullable: true
+        to:
+          type: string
+
+    TestPyramidCriterionDeltasDto:
+      type: object
+      properties:
+        D1:
+          $ref: "#/components/schemas/TestPyramidCriterionDeltaDto"
+        D2:
+          $ref: "#/components/schemas/TestPyramidCriterionDeltaDto"
+        D3:
+          $ref: "#/components/schemas/TestPyramidCriterionDeltaDto"
+        D4:
+          $ref: "#/components/schemas/TestPyramidCriterionDeltaDto"
+
+    TestPyramidRepoProgressDto:
+      type: object
+      required:
+        - repoId
+        - repoName
+        - baselineAt
+        - previousAt
+        - currentAt
+        - currentRunStatus
+        - maturity
+        - testsQaPercent
+        - testsQaPercentDelta
+        - layerDeltas
+        - baselineLayerDeltas
+        - criterionDeltas
+        - testPyramid
+        - testPyramidCriteria
+      properties:
+        repoId:
+          type: string
+          format: uuid
+        repoName:
+          type: string
+        baselineAt:
+          type: string
+          format: date-time
+        previousAt:
+          type: string
+          format: date-time
+          nullable: true
+        currentAt:
+          type: string
+          format: date-time
+        currentRunStatus:
+          $ref: "#/components/schemas/TestPyramidRunStatusDto"
+        maturity:
+          type: string
+          enum: [missing, emerging, established, mature]
+        testsQaPercent:
+          type: integer
+          minimum: 0
+          maximum: 100
+          nullable: true
+        testsQaPercentDelta:
+          type: integer
+          nullable: true
+        layerDeltas:
+          $ref: "#/components/schemas/TestPyramidLayerDeltasDto"
+        baselineLayerDeltas:
+          $ref: "#/components/schemas/TestPyramidLayerDeltasDto"
+        criterionDeltas:
+          $ref: "#/components/schemas/TestPyramidCriterionDeltasDto"
+        testPyramid:
+          $ref: "#/components/schemas/TestPyramidSnapshotDto"
+        testPyramidCriteria:
+          $ref: "#/components/schemas/TestPyramidCriteriaDto"
+        lineCoverage:
+          $ref: "#/components/schemas/TestPyramidLineCoverageDto"
+
+    TestPyramidLayerCoverageDto:
+      type: object
+      required: [presentRepos, applicableRepos, percent, missingRepoIds]
+      properties:
+        presentRepos:
+          type: integer
+          minimum: 0
+        applicableRepos:
+          type: integer
+          minimum: 0
+        percent:
+          type: integer
+          minimum: 0
+          maximum: 100
+          nullable: true
+        missingRepoIds:
+          type: array
+          items:
+            type: string
+            format: uuid
+
+    TestPyramidLayerCoverageMapDto:
+      type: object
+      required: [unit, integration, acceptance_bdd, contract, e2e]
+      properties:
+        unit:
+          $ref: "#/components/schemas/TestPyramidLayerCoverageDto"
+        integration:
+          $ref: "#/components/schemas/TestPyramidLayerCoverageDto"
+        acceptance_bdd:
+          $ref: "#/components/schemas/TestPyramidLayerCoverageDto"
+        contract:
+          $ref: "#/components/schemas/TestPyramidLayerCoverageDto"
+        e2e:
+          $ref: "#/components/schemas/TestPyramidLayerCoverageDto"
+
+    TestPyramidMaturityCountsDto:
+      type: object
+      required: [missing, emerging, established, mature]
+      properties:
+        missing:
+          type: integer
+          minimum: 0
+        emerging:
+          type: integer
+          minimum: 0
+        established:
+          type: integer
+          minimum: 0
+        mature:
+          type: integer
+          minimum: 0
+
+    TestPyramidCrossRepoMatchDto:
+      type: object
+      required: [sourceRepoId, targetRepoIds, referencedTargets]
+      properties:
+        sourceRepoId:
+          type: string
+          format: uuid
+        targetRepoIds:
+          type: array
+          items:
+            type: string
+            format: uuid
+        referencedTargets:
+          type: array
+          items:
+            type: string
+
+    WorkspaceTestPyramidSummaryDto:
+      type: object
+      required:
+        - reposWithPyramid
+        - reposFromDegradedRuns
+        - layerCoverage
+        - maturityCounts
+        - e2eCrossRepoCandidateRepoIds
+        - e2eCrossRepoMatches
+        - crossRepoE2ePresent
+      properties:
+        reposWithPyramid:
+          type: integer
+          minimum: 0
+        reposFromDegradedRuns:
+          type: array
+          description: >-
+            Repositories whose newest snapshot came from a run whose rubric grading did not
+            complete. Their pyramid is valid but Tests & QA scores are unavailable.
+          items:
+            type: string
+            format: uuid
+        layerCoverage:
+          $ref: "#/components/schemas/TestPyramidLayerCoverageMapDto"
+        maturityCounts:
+          $ref: "#/components/schemas/TestPyramidMaturityCountsDto"
+        e2eCrossRepoCandidateRepoIds:
+          type: array
+          items:
+            type: string
+            format: uuid
+        e2eCrossRepoMatches:
+          type: array
+          items:
+            $ref: "#/components/schemas/TestPyramidCrossRepoMatchDto"
+        crossRepoE2ePresent:
+          type: boolean
+          description: True only when an E2E target is matched to another repository in the workspace.
+
+    WorkspaceTestPyramidProgressDto:
+      type: object
+      required: [workspaceId, generatedAt, repos, workspace]
+      properties:
+        workspaceId:
+          type: string
+          format: uuid
+        generatedAt:
+          type: string
+          format: date-time
+        repos:
+          type: array
+          items:
+            $ref: "#/components/schemas/TestPyramidRepoProgressDto"
+        workspace:
+          $ref: "#/components/schemas/WorkspaceTestPyramidSummaryDto"
+
     ReadinessScoreHistoryPointDto:
       type: object
       required: [finishedAt, overallScore]
@@ -15918,6 +16547,10 @@ components:
           items:
             $ref: "#/components/schemas/ReadinessScoreHistoryDimensionScoreDto"
           description: Per-dimension percentages captured on this scan run.
+        testPyramid:
+          $ref: "#/components/schemas/TestPyramidSnapshotDto"
+        testPyramidCriteria:
+          $ref: "#/components/schemas/TestPyramidCriteriaDto"
 
     ReadinessRepoScoreHistoryDto:
       type: object
@@ -20976,3 +21609,206 @@ components:
           description: Org top-10 complexity hotspots by `ccMax` (current per-repo snapshots).
         sonar:
           $ref: "#/components/schemas/CodeInsightsSonarDto"
+
+    InsightsTestPyramidMaturityDto:
+      type: string
+      enum: [missing, emerging, established, mature]
+      description: >
+        Presence maturity (model A) using count-based layer presence
+        (`fileCount > 0`), not AF signal-inclusive `present`.
+
+    InsightsTestPyramidShapeLabelDto:
+      type: string
+      enum: [insufficient_data, base_heavy, balanced, top_heavy, middle_heavy]
+      description: >
+        Advisory shape label vs fixed 70/20/10. `insufficient_data` when total
+        classified test files < 10 (band percents are null).
+
+    InsightsTestPyramidShapeDto:
+      type: object
+      required: [label, totalClassifiedFiles, basePercent, middlePercent, topPercent, targets]
+      properties:
+        label:
+          $ref: "#/components/schemas/InsightsTestPyramidShapeLabelDto"
+        totalClassifiedFiles:
+          type: integer
+          minimum: 0
+          description: Sum of classified test **files** across the five layers (not test cases).
+        basePercent:
+          type: number
+          nullable: true
+          description: Share of classified files in unit (base). Null when insufficient_data.
+        middlePercent:
+          type: number
+          nullable: true
+          description: >
+            Share in integration + contract + acceptance_bdd (middle). Null when
+            insufficient_data.
+        topPercent:
+          type: number
+          nullable: true
+          description: Share in e2e (top). Null when insufficient_data.
+        targets:
+          type: object
+          required: [basePercent, middlePercent, topPercent]
+          properties:
+            basePercent: { type: number, enum: [70] }
+            middlePercent: { type: number, enum: [20] }
+            topPercent: { type: number, enum: [10] }
+
+    InsightsTestPyramidLayerCountsDto:
+      type: object
+      required: [unit, integration, acceptance_bdd, contract, e2e]
+      properties:
+        unit: { type: integer, minimum: 0 }
+        integration: { type: integer, minimum: 0 }
+        acceptance_bdd: { type: integer, minimum: 0 }
+        contract: { type: integer, minimum: 0 }
+        e2e: { type: integer, minimum: 0 }
+
+    InsightsTestPyramidLayerPresentDto:
+      type: object
+      required: [unit, integration, acceptance_bdd, contract, e2e]
+      properties:
+        unit: { type: boolean }
+        integration: { type: boolean }
+        acceptance_bdd: { type: boolean }
+        contract: { type: boolean }
+        e2e: { type: boolean }
+
+    InsightsTestPyramidLayerPresenceDto:
+      type: object
+      required: [presentRepos, applicableRepos, percent, missingRepoIds, missingRepoNames]
+      properties:
+        presentRepos: { type: integer, minimum: 0 }
+        applicableRepos: { type: integer, minimum: 0 }
+        percent:
+          type: integer
+          nullable: true
+          minimum: 0
+          maximum: 100
+        missingRepoIds:
+          type: array
+          items: { type: string, format: uuid }
+        missingRepoNames:
+          type: array
+          items: { type: string }
+
+    InsightsTestPyramidGapRepoDto:
+      type: object
+      required: [repoId, repoName]
+      properties:
+        repoId: { type: string, format: uuid }
+        repoName: { type: string }
+
+    InsightsTestPyramidGapsByLayerDto:
+      type: object
+      required: [unit, integration, acceptance_bdd, contract, e2e]
+      properties:
+        unit:
+          type: array
+          items: { $ref: "#/components/schemas/InsightsTestPyramidGapRepoDto" }
+        integration:
+          type: array
+          items: { $ref: "#/components/schemas/InsightsTestPyramidGapRepoDto" }
+        acceptance_bdd:
+          type: array
+          items: { $ref: "#/components/schemas/InsightsTestPyramidGapRepoDto" }
+        contract:
+          type: array
+          items: { $ref: "#/components/schemas/InsightsTestPyramidGapRepoDto" }
+        e2e:
+          type: array
+          items: { $ref: "#/components/schemas/InsightsTestPyramidGapRepoDto" }
+
+    InsightsTestPyramidMaturityCountsDto:
+      type: object
+      required: [missing, emerging, established, mature]
+      properties:
+        missing: { type: integer, minimum: 0 }
+        emerging: { type: integer, minimum: 0 }
+        established: { type: integer, minimum: 0 }
+        mature: { type: integer, minimum: 0 }
+
+    InsightsTestPyramidLayerPresenceMapDto:
+      type: object
+      required: [unit, integration, acceptance_bdd, contract, e2e]
+      properties:
+        unit: { $ref: "#/components/schemas/InsightsTestPyramidLayerPresenceDto" }
+        integration: { $ref: "#/components/schemas/InsightsTestPyramidLayerPresenceDto" }
+        acceptance_bdd: { $ref: "#/components/schemas/InsightsTestPyramidLayerPresenceDto" }
+        contract: { $ref: "#/components/schemas/InsightsTestPyramidLayerPresenceDto" }
+        e2e: { $ref: "#/components/schemas/InsightsTestPyramidLayerPresenceDto" }
+
+    InsightsTestPyramidSummaryDto:
+      type: object
+      required:
+        - workspaceId
+        - generatedAt
+        - reposWithPyramid
+        - reposFromDegradedRuns
+        - totalClassifiedFiles
+        - shape
+        - layerPresence
+        - maturityCounts
+        - gapsByLayer
+      properties:
+        workspaceId: { type: string, format: uuid }
+        generatedAt: { type: string, format: date-time }
+        reposWithPyramid: { type: integer, minimum: 0 }
+        reposFromDegradedRuns:
+          type: array
+          items: { type: string, format: uuid }
+          description: Repos whose newest pyramid came from a non-succeeded readiness run.
+        totalClassifiedFiles:
+          type: integer
+          minimum: 0
+          description: Workspace sum of classified test files (not cases).
+        shape:
+          $ref: "#/components/schemas/InsightsTestPyramidShapeDto"
+        layerPresence:
+          $ref: "#/components/schemas/InsightsTestPyramidLayerPresenceMapDto"
+        maturityCounts:
+          $ref: "#/components/schemas/InsightsTestPyramidMaturityCountsDto"
+        gapsByLayer:
+          $ref: "#/components/schemas/InsightsTestPyramidGapsByLayerDto"
+
+    InsightsTestPyramidRepoItemDto:
+      type: object
+      required:
+        - repoId
+        - repoName
+        - scannedAt
+        - currentRunStatus
+        - maturity
+        - layerFileCounts
+        - layerPresent
+        - totalClassifiedFiles
+        - shape
+      properties:
+        repoId: { type: string, format: uuid }
+        repoName: { type: string }
+        scannedAt: { type: string, format: date-time }
+        currentRunStatus:
+          $ref: "#/components/schemas/TestPyramidRunStatusDto"
+        maturity:
+          $ref: "#/components/schemas/InsightsTestPyramidMaturityDto"
+        layerFileCounts:
+          $ref: "#/components/schemas/InsightsTestPyramidLayerCountsDto"
+        layerPresent:
+          $ref: "#/components/schemas/InsightsTestPyramidLayerPresentDto"
+        totalClassifiedFiles: { type: integer, minimum: 0 }
+        shape:
+          $ref: "#/components/schemas/InsightsTestPyramidShapeDto"
+
+    InsightsTestPyramidRepoListDto:
+      type: object
+      required: [items, total, limit, offset]
+      properties:
+        items:
+          type: array
+          items:
+            $ref: "#/components/schemas/InsightsTestPyramidRepoItemDto"
+        total: { type: integer, minimum: 0 }
+        limit: { type: integer, minimum: 1 }
+        offset: { type: integer, minimum: 0 }