@thinkai/tai-api-contract 2.4.0 → 2.4.3

package/openapi/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: ThinkAI API
-  version: 2.4.0
+  version: 2.4.3
   description: >
     Contract surface for the AI Driven SDLC backend used by ThinkAI.
     Workspace-scoped routes use `/workspaces/{workspaceId}/...`.
@@ -48,6 +48,8 @@ tags:
     description: Per-user per-workspace preferences (§12)
   - name: OrgChartImport
     description: Org chart import via storage path (§14)
+  - name: AgenticFoundation
+    description: Agentic Foundation pillars (epic #278); reads stored repository readiness snapshots
 
 paths:
   /me:
@@ -1397,6 +1399,9 @@ paths:
     get:
       tags: [RepositoryReadiness]
       summary: Single repo readiness
+      description: >
+        Returns one stored repository scorecard with all eight dimensions and nested issues.
+        Unknown `repoId` or a repo that belongs to another workspace returns `404` (no cross-tenant leakage).
       operationId: getReadinessRepo
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
@@ -1408,13 +1413,353 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/RepoReadinessScoreDto"
+        "400":
+          description: Malformed `repoId` (not a UUID)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace or repository not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
+  /workspaces/{workspaceId}/agentic-foundation/dashboard:
+    get:
+      tags: [AgenticFoundation]
+      summary: Agentic Foundation dashboard
+      description: >
+        Returns stored repository readiness scorecards plus a flattened issue queue for the
+        Agentic Foundation dashboard surfaces. This is read-only and does not run scoring on
+        the request path (issue #279). Field `generatedAt` is the server timestamp when this JSON
+        payload was assembled; it is not the same as per-repo `lastAnalyzed` on `RepoReadinessScoreDto`.
+      operationId: getAgenticFoundationDashboard
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Dashboard scorecards and issue queue
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AgenticFoundationDashboardDto"
+              examples:
+                emptyWorkspace:
+                  summary: No repos analyzed yet
+                  value:
+                    workspaceId: 00000000-0000-0000-0000-000000000001
+                    generatedAt: "2026-05-12T12:00:00.000Z"
+                    summary:
+                      repoCount: 0
+                      averageOverallScore: 0
+                      issueCount: 0
+                      criticalIssueCount: 0
+                    repos: []
+                    issueQueue: []
+        "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}/agentic-foundation/agentic-readiness:
+    get:
+      tags: [AgenticFoundation]
+      summary: Agentic readiness pillar (stored dimension slice)
+      description: >
+        Returns `RepoReadinessScoreDto` rows with only the `ai-agent-readiness` dimension populated
+        per repo. Same auth and persistence source as `GET .../readiness/repos` (issue #280).
+      operationId: getAgenticFoundationAgenticReadiness
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Repositories with ai-agent-readiness slice
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/RepoReadinessScoreDto"
+              examples:
+                singleRepoSlice:
+                  summary: One repo, single pillar dimension
+                  value:
+                    - repoId: 00000000-0000-0000-0000-000000000002
+                      repoName: api-gateway
+                      language: typescript
+                      overallScore: 67
+                      dimensions:
+                        - dimensionId: ai-agent-readiness
+                          score: 2
+                          maxScore: 3
+                          issues: []
+                      lastAnalyzed: "2026-05-12T12:00:00.000Z"
+                      teamId: null
+                      provider:
+                        kind: github
+                        slug: acme/api-gateway
+                        webUrl: https://github.com/acme/api-gateway
+                        defaultBranch: main
+                        externalId: null
+                        hostBaseUrl: null
+                      analysisStatus: idle
+                      activeRunId: null
         "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}/agentic-foundation/repository-health:
+    get:
+      tags: [AgenticFoundation]
+      summary: Repository health pillar (repo-hygiene slice)
+      description: Returns per-repo `repo-hygiene` dimension only (issue #281).
+      operationId: getAgenticFoundationRepositoryHealth
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Repositories with repo-hygiene slice
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/RepoReadinessScoreDto"
+        "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}/agentic-foundation/codebase-quality:
+    get:
+      tags: [AgenticFoundation]
+      summary: Codebase quality pillar (stack-quality slice)
+      description: Returns per-repo `stack-quality` dimension only (issue #282).
+      operationId: getAgenticFoundationCodebaseQuality
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Repositories with stack-quality slice
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/RepoReadinessScoreDto"
+        "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}/agentic-foundation/test-qa:
+    get:
+      tags: [AgenticFoundation]
+      summary: Test and QA pillar (tests-qa slice)
+      description: Returns per-repo `tests-qa` dimension only (issue #283).
+      operationId: getAgenticFoundationTestQa
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Repositories with tests-qa slice
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/RepoReadinessScoreDto"
+        "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}/agentic-foundation/observability:
+    get:
+      tags: [AgenticFoundation]
+      summary: Observability pillar (observability slice)
+      description: Returns per-repo `observability` dimension only (issue #284).
+      operationId: getAgenticFoundationObservability
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Repositories with observability slice
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/RepoReadinessScoreDto"
+        "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}/agentic-foundation/api-contract:
+    get:
+      tags: [AgenticFoundation]
+      summary: API contract pillar (api-contracts slice)
+      description: Returns per-repo `api-contracts` dimension only (issue #285).
+      operationId: getAgenticFoundationApiContract
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Repositories with api-contracts slice
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/RepoReadinessScoreDto"
+        "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}/agentic-foundation/platform-governance:
+    get:
+      tags: [AgenticFoundation]
+      summary: Platform governance pillar (platform-governance slice)
+      description: Returns per-repo `platform-governance` dimension only (issue #286).
+      operationId: getAgenticFoundationPlatformGovernance
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Repositories with platform-governance slice
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/RepoReadinessScoreDto"
+        "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}/agentic-foundation/delivery-governance:
+    get:
+      tags: [AgenticFoundation]
+      summary: Delivery governance pillar (delivery slice)
+      description: Returns per-repo `delivery` dimension only (issue #287).
+      operationId: getAgenticFoundationDeliveryGovernance
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Repositories with delivery slice
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/RepoReadinessScoreDto"
+        "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}/agentic-foundation/ai-resolution-hub:
+    get:
+      tags: [AgenticFoundation]
+      summary: AI resolution hub (full readiness scorecards)
+      description: >
+        Returns the same payload as `GET .../readiness/repos` (all dimensions per repo) for
+        cross-pillar hub views (issue #288).
+      operationId: getAgenticFoundationAiResolutionHub
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Full repository readiness scorecards
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/RepoReadinessScoreDto"
+        "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}/readiness/dimensions:
     get:
       tags: [RepositoryReadiness]
       summary: Readiness dimensions catalog
+      description: >
+        Returns static rubric metadata (id, name, description, maxScore) aligned with the readiness
+        scanner dimensions. Does not run scoring on the request path.
       operationId: listReadinessDimensions
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
@@ -1429,11 +1774,21 @@ paths:
                   $ref: "#/components/schemas/ReadinessDimensionDto"
         "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}/readiness/fixes:
     get:
       tags: [RepositoryReadiness]
       summary: List fix requests
+      description: >
+        Returns persisted fix-queue rows for the workspace (newest first). Empty array when none exist.
       operationId: listReadinessFixes
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
@@ -1448,9 +1803,21 @@ paths:
                   $ref: "#/components/schemas/FixRequestDto"
         "401":
           $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
     post:
       tags: [RepositoryReadiness]
       summary: Enqueue fix for an issue
+      description: >
+        Creates a fix request with `status: queued` when `issueId` belongs to `repoId` in this workspace.
+        Requires workspace editor or admin. Re-posting the same `issueId` and `repoId` returns the
+        existing row (idempotent).
       operationId: postReadinessFix
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
@@ -1460,15 +1827,34 @@ paths:
           application/json:
             schema:
               $ref: "#/components/schemas/CreateFixRequestBodyDto"
+            examples:
+              enqueue:
+                value:
+                  issueId: "22222222-2222-2222-2222-222222222222"
+                  repoId: "11111111-1111-4111-8111-111111111111"
       responses:
         "200":
-          description: Fix request created
+          description: Fix request created or existing row returned
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/FixRequestDto"
+        "400":
+          description: Invalid body or malformed `repoId` (not a UUID)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
         "401":
           $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace not found, or issue/repo pair not in workspace
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
 
   /workspaces/{workspaceId}/squad:
     get:
@@ -1795,6 +2181,7 @@ components:
       required: true
       schema:
         type: string
+        format: uuid
     ProjectId:
       name: projectId
       in: path
@@ -2598,6 +2985,13 @@ components:
       type: string
       enum: [queued, running, succeeded, failed, partial_failed]
 
+    ReadinessRepoAnalysisStatusDto:
+      type: string
+      enum: [idle, queued, running]
+      description: >
+        Whether an AI readiness analysis run is queued or in progress for this repository slug.
+        `idle` means no `queued`/`running` row exists in `tai_workspace_readiness_runs`.
+
     ReadinessRunSummaryDto:
       type: object
       required: [runId, status, providerSlug, errorCode, errorDetail, repoId, createdAt, finishedAt]
@@ -2673,7 +3067,15 @@ components:
 
     RepoReadinessScoreDto:
       type: object
-      required: [repoId, repoName, language, overallScore, dimensions, lastAnalyzed, provider]
+      required:
+        - repoId
+        - repoName
+        - language
+        - overallScore
+        - dimensions
+        - lastAnalyzed
+        - provider
+        - analysisStatus
       properties:
         repoId:
           type: string
@@ -2702,6 +3104,87 @@ components:
           nullable: true
         provider:
           $ref: "#/components/schemas/RepoProviderDto"
+        analysisStatus:
+          $ref: "#/components/schemas/ReadinessRepoAnalysisStatusDto"
+        activeRunId:
+          type: string
+          format: uuid
+          nullable: true
+          description: Present when `analysisStatus` is `queued` or `running`; use with `GET .../readiness/runs/{runId}`.
+
+    AgenticFoundationDashboardSummaryDto:
+      type: object
+      required: [repoCount, averageOverallScore, issueCount, criticalIssueCount]
+      properties:
+        repoCount:
+          type: integer
+          minimum: 0
+        averageOverallScore:
+          type: integer
+          minimum: 0
+          maximum: 100
+        issueCount:
+          type: integer
+          minimum: 0
+        criticalIssueCount:
+          type: integer
+          minimum: 0
+
+    AgenticFoundationDashboardIssueDto:
+      type: object
+      required:
+        [id, repoId, repoName, provider, dimensionId, severity, title, description, filePath, fixStatus]
+      properties:
+        id:
+          type: string
+          format: uuid
+        repoId:
+          type: string
+          format: uuid
+        repoName:
+          type: string
+          maxLength: 256
+        provider:
+          $ref: "#/components/schemas/RepoProviderDto"
+        dimensionId:
+          $ref: "#/components/schemas/ReadinessDimensionId"
+        severity:
+          type: string
+          enum: [critical, high, medium, low]
+        title:
+          type: string
+          maxLength: 256
+        description:
+          type: string
+          maxLength: 2048
+        filePath:
+          type: string
+          maxLength: 512
+          nullable: true
+        fixStatus:
+          type: string
+          enum: [open, pr-pending, fixed]
+
+    AgenticFoundationDashboardDto:
+      type: object
+      required: [workspaceId, generatedAt, summary, repos, issueQueue]
+      properties:
+        workspaceId:
+          type: string
+          format: uuid
+        generatedAt:
+          type: string
+          format: date-time
+        summary:
+          $ref: "#/components/schemas/AgenticFoundationDashboardSummaryDto"
+        repos:
+          type: array
+          items:
+            $ref: "#/components/schemas/RepoReadinessScoreDto"
+        issueQueue:
+          type: array
+          items:
+            $ref: "#/components/schemas/AgenticFoundationDashboardIssueDto"
 
     FixRequestDto:
       type: object
@@ -2737,8 +3220,12 @@ components:
       properties:
         issueId:
           type: string
+          format: uuid
+          description: Readiness issue id from stored scorecard data
         repoId:
           type: string
+          format: uuid
+          description: Workspace repository id that owns the issue
 
     PhaseRoleDto:
       type: object

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thinkai/tai-api-contract",
-  "version": "2.4.0",
+  "version": "2.4.3",
   "private": false,
   "type": "module",
   "main": "dist/index.js",