@thinkai/tai-api-contract 2.61.0 → 2.63.0

package/openapi/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: ThinkAI API
-  version: 2.61.0
+  version: 2.63.0
   description: >
     Contract surface for the AI Driven SDLC backend used by ThinkAI.
     Workspace-scoped routes use `/workspaces/{workspaceId}/...`.
@@ -54,6 +54,8 @@ 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: WorkspaceActivity
     description: Workspace-wide lifecycle activity log — repo add/remove/re-add and integration lifecycle events (issue #515).
   - name: PlatformAdmin
@@ -2610,6 +2612,115 @@ 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}/integrations/ai-tool/{provider}/members:
     get:
       tags: [Workspace]
@@ -3008,6 +3119,9 @@ paths:
       operationId: postGithubInstallUrl
       description: >
         Creates a GitHub App installation URL scoped to the workspace and caller.
+        Default intent `connect` installs ThinkAI Platform Insights (read).
+        Intent `enable_fixes` installs ThinkAI Platform Automations (write) for the Insights
+        installation identified by `installationId`.
         Body is optional; when omitted, defaults to `/onboarding/integrations` return path.
         Optional `pickerSession` (from user OAuth org picker) recovers `returnPath` from the server-side picker snapshot when the multi-hop authorize→install flow should return to the page where OAuth started.
       security:
@@ -3043,6 +3157,91 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorMessageDto"
+        "503":
+          description: Requested GitHub App is not configured
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
+  /workspaces/{workspaceId}/integrations/github/installations/{installationId}/automated-fixes/enable:
+    post:
+      tags: [Integrations]
+      summary: Enable automated fixes for a GitHub installation
+      operationId: postGithubAutomatedFixesEnable
+      description: >
+        Workspace-level enable for automated fixes on an Insights (read) installation.
+        If an Automations (write) installation is already linked, flips `automatedFixesEnabled`
+        without reinstalling. Otherwise returns `outcome: needs_install` so the client can
+        call install-url with intent=enable_fixes.
+      security:
+        - bearerAuth: []
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - name: installationId
+          in: path
+          required: true
+          schema:
+            type: string
+            minLength: 1
+            maxLength: 64
+      responses:
+        "200":
+          description: Enable result
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/GithubAutomatedFixesEnableResponseDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace or installation not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "503":
+          description: Automations GitHub App not configured
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
+  /workspaces/{workspaceId}/integrations/github/installations/{installationId}/automated-fixes:
+    delete:
+      tags: [Integrations]
+      summary: Disable automated fixes for a GitHub installation
+      operationId: deleteGithubAutomatedFixes
+      description: >
+        Workspace-level disable. Clears `automatedFixesEnabled` but keeps the linked Automations
+        write installation id so re-enable does not require reinstall. Does not uninstall the
+        Automations app from GitHub.
+      security:
+        - bearerAuth: []
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - name: installationId
+          in: path
+          required: true
+          schema:
+            type: string
+            minLength: 1
+            maxLength: 64
+      responses:
+        "204":
+          description: Automated fixes disabled (or already disabled)
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace or installation not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
 
   /workspaces/{workspaceId}/integrations/github/user-authorize-url:
     post:
@@ -5609,6 +5808,31 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorMessageDto"
+        "422":
+          description: GitHub installation lacks write permissions required for automated fix PRs
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/GithubWritePermissionsRequiredErrorDto"
+              examples:
+                write_required:
+                  value:
+                    error: github_write_permissions_required
+                    missingPermissions:
+                      - name: contents
+                        required: write
+                        granted: read
+                      - name: pull_requests
+                        required: write
+                        granted: read
+                    manageUrl: https://github.com/settings/installations/12345
+                    writeUpgradeMessage: "Automated fixes need write access to your repositories: Contents (Read and write) and Pull requests (Read and write). Fixes open pull requests you review — nothing is merged automatically. Approve the update on GitHub to enable fix PRs."
+        "503":
+          description: GitHub installation permissions could not be verified
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/GithubPermissionsCheckFailedErrorDto"
 
   /workspaces/{workspaceId}/readiness/fixes/{fixId}/retrigger:
     post:
@@ -5652,6 +5876,18 @@ paths:
                   value:
                     error: Fix is currently generating and cannot be superseded
                     code: fix_generating
+        "422":
+          description: GitHub installation lacks write permissions required for automated fix PRs
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/GithubWritePermissionsRequiredErrorDto"
+        "503":
+          description: GitHub installation permissions could not be verified
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/GithubPermissionsCheckFailedErrorDto"
 
   /workspaces/{workspaceId}/cursor/platform-key-consent:
     put:
@@ -6290,6 +6526,37 @@ paths:
 
   # ── Your AI Journey (/dashboard) — epic #267 ─────────────────────────────
 
+  /workspaces/{workspaceId}/your-ai-journey/hero:
+    get:
+      tags: [YourAiJourney]
+      summary: First-paint hero payload for the /dashboard page
+      description: >
+        Returns analytics and productivity in one response so the dashboard hero can
+        paint with a single RTT (auth + membership checked once). Nested payloads match
+        the dedicated analytics and productivity routes and reuse those routes' 60s
+        caches (there is no separate hero-level cache). `generatedAt` on the hero
+        envelope and both nested payloads is set to the same assembly timestamp.
+      operationId: getYourAiJourneyHero
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Hero bootstrap payload
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/YourAiJourneyHeroDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
   /workspaces/{workspaceId}/your-ai-journey/analytics:
     get:
       tags: [YourAiJourney]
@@ -6929,6 +7196,16 @@ components:
       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
@@ -10723,9 +11000,50 @@ components:
           nullable: true
           description: Null when the installation has not granted this permission.
 
+    GithubWritePermissionsRequiredErrorDto:
+      type: object
+      additionalProperties: false
+      required: [error, missingPermissions]
+      properties:
+        error:
+          type: string
+          enum: [github_write_permissions_required]
+        missingPermissions:
+          type: array
+          items:
+            $ref: "#/components/schemas/GithubMissingPermissionDto"
+        manageUrl:
+          type: string
+          nullable: true
+          description: GitHub installation settings URL to approve write permissions.
+        writeUpgradeMessage:
+          type: string
+          nullable: true
+          description: Human-readable summary of the write permission upgrade.
+
+    GithubPermissionsCheckFailedErrorDto:
+      type: object
+      additionalProperties: false
+      required: [error]
+      properties:
+        error:
+          type: string
+          enum: [github_permissions_check_failed]
+          description: GitHub installation permissions could not be verified (transient upstream failure).
+
     GithubInstallationSummaryDto:
       type: object
-      required: [installationId, account, repos, permissionsUpgradeRequired]
+      required:
+        - installationId
+        - account
+        - repos
+        - permissionsUpgradeRequired
+        - corePermissionsOk
+        - writePermissionsOk
+        - writePermissionsUpgradeRequired
+        - automatedFixesEnabled
+        - writeAppInstalled
+        - canEnableAutomatedFixes
       properties:
         installationId:
           type: string
@@ -10747,16 +11065,61 @@ components:
         permissionsUpgradeRequired:
           type: boolean
           description: >
-            True when this installation's granted permissions are below what the ThinkAI GitHub App
-            currently requests.
+            True when this installation lacks core read permissions required for connect and analysis.
+            Alias for `!corePermissionsOk`.
+        corePermissionsOk:
+          type: boolean
+          description: >
+            True when installation grants read permissions for repository analysis (contents, metadata,
+            pull requests, and members for org installs).
+        writePermissionsOk:
+          type: boolean
+          description: >
+            True when automated fixes are enabled and the linked Automations (write) installation
+            grants write permissions required for fix PRs.
+        writePermissionsUpgradeRequired:
+          type: boolean
+          description: Alias for `!writePermissionsOk`.
         missingPermissions:
           type: array
           items:
             $ref: "#/components/schemas/GithubMissingPermissionDto"
+          description: Core read permissions still needed for connect and analysis.
+        missingWritePermissions:
+          type: array
+          items:
+            $ref: "#/components/schemas/GithubMissingPermissionDto"
+          description: Write permissions still needed for automated fix PRs.
         upgradeMessage:
           type: string
           nullable: true
-          description: Human-readable summary for UI when permissionsUpgradeRequired is true.
+          description: Human-readable summary for UI when core permissions are missing.
+        writeUpgradeMessage:
+          type: string
+          nullable: true
+          description: Human-readable summary for UI when write permissions are missing.
+        automatedFixesEnabled:
+          type: boolean
+          description: >
+            True when this workspace has enabled automated fixes for this Insights (read)
+            installation and linked a ThinkAI Platform Automations (write) installation.
+        writeAppInstalled:
+          type: boolean
+          description: True when an Automations (write) GitHub App installation is linked.
+        writeInstallationId:
+          type: string
+          nullable: true
+          description: GitHub installation id for the Automations (write) app, when linked.
+        writeManageUrl:
+          type: string
+          format: uri
+          nullable: true
+          description: GitHub settings URL for the Automations (write) installation.
+        canEnableAutomatedFixes:
+          type: boolean
+          description: >
+            True when the Automations app is configured and automated fixes are not yet
+            enabled for this installation (UI may show Enable automated fixes).
 
     GithubPendingApprovalDto:
       type: object
@@ -11041,7 +11404,13 @@ components:
 
     GithubInstallationStatusDto:
       type: object
-      required: [installed, installations, permissionsUpgradeRequired]
+      required:
+        - installed
+        - installations
+        - permissionsUpgradeRequired
+        - corePermissionsOk
+        - writePermissionsOk
+        - writePermissionsUpgradeRequired
       properties:
         installed:
           type: boolean
@@ -11051,7 +11420,25 @@ components:
             $ref: "#/components/schemas/GithubInstallationSummaryDto"
         permissionsUpgradeRequired:
           type: boolean
-          description: True if any connected installation is under-permissioned.
+          description: True if any connected installation lacks core read permissions. Alias for `!corePermissionsOk`.
+        corePermissionsOk:
+          type: boolean
+          description: True when every connected installation grants core read permissions.
+        writePermissionsOk:
+          type: boolean
+          description: True when every connected installation grants write permissions for automated fixes.
+        writePermissionsUpgradeRequired:
+          type: boolean
+          description: True when any connected installation lacks write permissions for automated fixes.
+        missingWritePermissions:
+          type: array
+          items:
+            $ref: "#/components/schemas/GithubMissingPermissionDto"
+          description: Aggregated write permissions missing on installations that lack write access.
+        writeUpgradeMessage:
+          type: string
+          nullable: true
+          description: Human-readable summary when write permissions are missing.
         pendingApproval:
           nullable: true
           allOf:
@@ -11127,6 +11514,17 @@ components:
           format: uri
           maxLength: 256
           description: SPA origin to redirect back to after OAuth; must match server spaOrigins allowlist.
+        intent:
+          type: string
+          enum: [connect, enable_fixes]
+          description: >
+            connect installs ThinkAI Platform Insights (read). enable_fixes installs ThinkAI Platform
+            Automations (write) for the Insights installation identified by installationId.
+        installationId:
+          type: string
+          minLength: 1
+          maxLength: 64
+          description: Insights (read) installation id required when intent is enable_fixes.
 
     GithubInstallUrlResponseDto:
       type: object
@@ -11142,6 +11540,22 @@ components:
           minLength: 16
           maxLength: 128
 
+    GithubAutomatedFixesEnableResponseDto:
+      type: object
+      additionalProperties: false
+      required: [outcome]
+      properties:
+        outcome:
+          type: string
+          enum: [enabled, needs_install]
+          description: >
+            enabled — write app already linked and flag flipped; needs_install — client should
+            call install-url with intent=enable_fixes.
+        status:
+          allOf:
+            - $ref: "#/components/schemas/GithubInstallationStatusDto"
+          description: Present when outcome is enabled.
+
     GithubUserAuthorizeUrlRequestDto:
       type: object
       additionalProperties: false
@@ -13183,6 +13597,24 @@ components:
             totalFixedIssues:
               type: integer
 
+    YourAiJourneyHeroDto:
+      type: object
+      required: [workspaceId, generatedAt, analytics, productivity]
+      properties:
+        workspaceId:
+          type: string
+          format: uuid
+        generatedAt:
+          type: string
+          format: date-time
+          description: >
+            Assembly timestamp for this hero response; also written onto
+            analytics.generatedAt and productivity.generatedAt so all three match.
+        analytics:
+          $ref: "#/components/schemas/YourAiJourneyAnalyticsDto"
+        productivity:
+          $ref: "#/components/schemas/DashboardProductivityDto"
+
     YourAiJourneyAnalyticsDto:
       type: object
       required: [workspaceId, generatedAt, windowStart, windowEnd, journey, readiness, prSignals]
@@ -13874,3 +14306,200 @@ 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