@thinkai/tai-api-contract 2.187.0 → 2.188.0

package/openapi/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: ThinkAI API
-  version: 2.187.0
+  version: 2.188.0
   description: >
     Contract surface for the AI Driven SDLC backend used by ThinkAI.
     Workspace-scoped routes use `/workspaces/{workspaceId}/...`.
@@ -9326,6 +9326,143 @@ paths:
               schema:
                 $ref: "#/components/schemas/GithubPermissionsCheckFailedErrorDto"
 
+  /workspaces/{workspaceId}/rules-skills/validate:
+    post:
+      tags: [AgenticFoundation]
+      summary: Validate agent rules and skills for a repository
+      description: >
+        Clones the connected GitHub repository via the workspace GitHub App installation
+        and runs the shared Rules & Skills validate engine (structural + soft quality).
+        Assessed tools come from the latest **succeeded** readiness scan
+        (`agent_tool_assessed`: `cursor` | `claude-code` | `both`). Returns draft
+        `proposedFiles` for review (not committed). Workspace member auth; write
+        permissions are not required for validate-only.
+      operationId: postRulesSkillsValidate
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/RulesSkillsValidateRequestDto"
+            examples:
+              validate:
+                value:
+                  repoId: "11111111-1111-4111-8111-111111111111"
+                  pathPrefixes:
+                    - ".cursor"
+      responses:
+        "200":
+          description: Validation result with findings and draft proposed files
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/RulesSkillsValidateResponseDto"
+        "400":
+          description: Invalid body (e.g. malformed repoId)
+          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 / not connected
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "422":
+          description: >
+            No succeeded readiness scan for the repo (`code: readiness_scan_required`),
+            or repository is not a GitHub-connected readiness repo.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              examples:
+                readiness_scan_required:
+                  value:
+                    error: Run an Agentic Foundation readiness scan before validating rules and skills
+                    code: readiness_scan_required
+        "503":
+          description: Clone or GitHub App configuration failed
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
+  /workspaces/{workspaceId}/rules-skills/pull-requests:
+    post:
+      tags: [AgenticFoundation]
+      summary: Open a Rules & Skills remediation pull request
+      description: >
+        Applies `proposedFiles` (or a future create-mode session) onto a non-default
+        branch via the Automations GitHub App installation and opens a pull request.
+        Never pushes to the default branch. PR title/body identify the change as
+        platform-generated and link back to `/agentic-foundation/rules-skills`.
+        Requires workspace editor or admin. Same write-permission gate as readiness fixes.
+      operationId: postRulesSkillsPullRequest
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/RulesSkillsOpenPullRequestRequestDto"
+            examples:
+              validateMode:
+                value:
+                  repoId: "11111111-1111-4111-8111-111111111111"
+                  mode: validate
+                  proposedFiles:
+                    - path: ".cursor/rules/foo.mdc"
+                      action: rename
+                      previousPath: ".cursor/rules/foo.md"
+                      content: "---\ndescription: example\nglobs: \"**/*\"\n---\n"
+      responses:
+        "200":
+          description: Pull request created
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/RulesSkillsOpenPullRequestResponseDto"
+        "400":
+          description: >
+            Missing proposed files or invalid body (`code: proposed_files_required`).
+          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"
+        "422":
+          description: GitHub installation lacks write permissions required for automated PRs
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/GithubWritePermissionsRequiredErrorDto"
+        "503":
+          description: GitHub installation permissions could not be verified, or PR create failed
+          content:
+            application/json:
+              schema:
+                oneOf:
+                  - $ref: "#/components/schemas/GithubPermissionsCheckFailedErrorDto"
+                  - $ref: "#/components/schemas/ErrorMessageDto"
+
   /workspaces/{workspaceId}/readiness/issues/{issueId}/fix-guide:
     get:
       tags: [RepositoryReadiness]
@@ -22542,6 +22679,170 @@ components:
             Required when the issue has unresolvedChoices. Must be one of those labels.
             Stored on the fix row and stated in the worker prompt.
 
+    RulesSkillsAssessedTools:
+      type: string
+      enum: [cursor, claude-code, both]
+      description: >
+        From the latest succeeded readiness scan (`agent_tool_assessed`). Never invent
+        `both` without scan evidence.
+
+    RulesSkillsValidateRequestDto:
+      type: object
+      additionalProperties: false
+      required: [repoId]
+      properties:
+        repoId:
+          type: string
+          format: uuid
+        pathPrefixes:
+          type: array
+          maxItems: 32
+          items:
+            type: string
+            maxLength: 512
+          description: Optional relative path prefixes limiting the validate walk.
+
+    RulesSkillsFindingDto:
+      type: object
+      additionalProperties: false
+      required: [id, kind, severity, code, path, message, criterionIds]
+      properties:
+        id:
+          type: string
+        kind:
+          type: string
+          enum: [structural, soft]
+        severity:
+          type: string
+          enum: [fail, warn]
+        code:
+          type: string
+        path:
+          type: string
+        message:
+          type: string
+        criterionIds:
+          type: array
+          items:
+            type: string
+            enum: [A1, A2, A3, A3a, A3b, A3c, A11]
+          description: Empty when unmapped structural noise.
+
+    RulesSkillsSoftQualityCheckDto:
+      type: object
+      additionalProperties: false
+      required: [code, status]
+      properties:
+        code:
+          type: string
+        status:
+          type: string
+          enum: [pass, fail, warn, skip]
+        message:
+          type: string
+        path:
+          type: string
+
+    RulesSkillsSoftQualitySummaryDto:
+      type: object
+      additionalProperties: false
+      required: [passed, failCount, warnCount, checks]
+      properties:
+        passed:
+          type: boolean
+          description: True when there are no soft-quality fail findings (warns allowed).
+        failCount:
+          type: integer
+          minimum: 0
+        warnCount:
+          type: integer
+          minimum: 0
+        checks:
+          type: array
+          items:
+            $ref: "#/components/schemas/RulesSkillsSoftQualityCheckDto"
+
+    RulesSkillsProposedFileDto:
+      type: object
+      additionalProperties: false
+      required: [path, action]
+      properties:
+        path:
+          type: string
+          maxLength: 1024
+        action:
+          type: string
+          enum: [create, update, delete, rename]
+        content:
+          type: string
+          description: Full file contents for create/update/rename target.
+        previousPath:
+          type: string
+          maxLength: 1024
+          description: Source path when action is rename.
+
+    RulesSkillsValidateResponseDto:
+      type: object
+      additionalProperties: false
+      required: [assessedTools, findings, softQualitySummary, proposedFiles]
+      properties:
+        assessedTools:
+          $ref: "#/components/schemas/RulesSkillsAssessedTools"
+        findings:
+          type: array
+          items:
+            $ref: "#/components/schemas/RulesSkillsFindingDto"
+        softQualitySummary:
+          $ref: "#/components/schemas/RulesSkillsSoftQualitySummaryDto"
+        proposedFiles:
+          type: array
+          items:
+            $ref: "#/components/schemas/RulesSkillsProposedFileDto"
+        note:
+          type: string
+          description: Quiet-case note (e.g. empty tree under pathPrefixes).
+
+    RulesSkillsOpenPullRequestRequestDto:
+      type: object
+      additionalProperties: false
+      required: [repoId, mode]
+      properties:
+        repoId:
+          type: string
+          format: uuid
+        mode:
+          type: string
+          enum: [validate, create]
+        sessionId:
+          type: string
+          format: uuid
+          description: Reserved for Create-mode sessions; validate mode uses proposedFiles.
+        proposedFiles:
+          type: array
+          minItems: 1
+          maxItems: 200
+          items:
+            $ref: "#/components/schemas/RulesSkillsProposedFileDto"
+        title:
+          type: string
+          maxLength: 200
+        body:
+          type: string
+          maxLength: 8000
+
+    RulesSkillsOpenPullRequestResponseDto:
+      type: object
+      additionalProperties: false
+      required: [prUrl, prNumber, branchName]
+      properties:
+        prUrl:
+          type: string
+          format: uri
+        prNumber:
+          type: integer
+        branchName:
+          type: string
+
     PhaseRoleDto:
       type: object
       required: [phase, assignment]

package/package.json

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

package/src/generated/openapi.ts

@@ -3344,6 +3344,46 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/workspaces/{workspaceId}/rules-skills/validate": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Validate agent rules and skills for a repository
+         * @description Clones the connected GitHub repository via the workspace GitHub App installation and runs the shared Rules & Skills validate engine (structural + soft quality). Assessed tools come from the latest **succeeded** readiness scan (`agent_tool_assessed`: `cursor` | `claude-code` | `both`). Returns draft `proposedFiles` for review (not committed). Workspace member auth; write permissions are not required for validate-only.
+         */
+        post: operations["postRulesSkillsValidate"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/workspaces/{workspaceId}/rules-skills/pull-requests": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Open a Rules & Skills remediation pull request
+         * @description Applies `proposedFiles` (or a future create-mode session) onto a non-default branch via the Automations GitHub App installation and opens a pull request. Never pushes to the default branch. PR title/body identify the change as platform-generated and link back to `/agentic-foundation/rules-skills`. Requires workspace editor or admin. Same write-permission gate as readiness fixes.
+         */
+        post: operations["postRulesSkillsPullRequest"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/workspaces/{workspaceId}/readiness/issues/{issueId}/fix-guide": {
         parameters: {
             query?: never;
@@ -9243,6 +9283,80 @@ export interface components {
             /** @description Required when the issue has unresolvedChoices. Must be one of those labels. Stored on the fix row and stated in the worker prompt. */
             patternChoice?: string;
         };
+        /**
+         * @description From the latest succeeded readiness scan (`agent_tool_assessed`). Never invent `both` without scan evidence.
+         * @enum {string}
+         */
+        RulesSkillsAssessedTools: "cursor" | "claude-code" | "both";
+        RulesSkillsValidateRequestDto: {
+            /** Format: uuid */
+            repoId: string;
+            /** @description Optional relative path prefixes limiting the validate walk. */
+            pathPrefixes?: string[];
+        };
+        RulesSkillsFindingDto: {
+            id: string;
+            /** @enum {string} */
+            kind: "structural" | "soft";
+            /** @enum {string} */
+            severity: "fail" | "warn";
+            code: string;
+            path: string;
+            message: string;
+            /** @description Empty when unmapped structural noise. */
+            criterionIds: ("A1" | "A2" | "A3" | "A3a" | "A3b" | "A3c" | "A11")[];
+        };
+        RulesSkillsSoftQualityCheckDto: {
+            code: string;
+            /** @enum {string} */
+            status: "pass" | "fail" | "warn" | "skip";
+            message?: string;
+            path?: string;
+        };
+        RulesSkillsSoftQualitySummaryDto: {
+            /** @description True when there are no soft-quality fail findings (warns allowed). */
+            passed: boolean;
+            failCount: number;
+            warnCount: number;
+            checks: components["schemas"]["RulesSkillsSoftQualityCheckDto"][];
+        };
+        RulesSkillsProposedFileDto: {
+            path: string;
+            /** @enum {string} */
+            action: "create" | "update" | "delete" | "rename";
+            /** @description Full file contents for create/update/rename target. */
+            content?: string;
+            /** @description Source path when action is rename. */
+            previousPath?: string;
+        };
+        RulesSkillsValidateResponseDto: {
+            assessedTools: components["schemas"]["RulesSkillsAssessedTools"];
+            findings: components["schemas"]["RulesSkillsFindingDto"][];
+            softQualitySummary: components["schemas"]["RulesSkillsSoftQualitySummaryDto"];
+            proposedFiles: components["schemas"]["RulesSkillsProposedFileDto"][];
+            /** @description Quiet-case note (e.g. empty tree under pathPrefixes). */
+            note?: string;
+        };
+        RulesSkillsOpenPullRequestRequestDto: {
+            /** Format: uuid */
+            repoId: string;
+            /** @enum {string} */
+            mode: "validate" | "create";
+            /**
+             * Format: uuid
+             * @description Reserved for Create-mode sessions; validate mode uses proposedFiles.
+             */
+            sessionId?: string;
+            proposedFiles?: components["schemas"]["RulesSkillsProposedFileDto"][];
+            title?: string;
+            body?: string;
+        };
+        RulesSkillsOpenPullRequestResponseDto: {
+            /** Format: uri */
+            prUrl: string;
+            prNumber: number;
+            branchName: string;
+        };
         PhaseRoleDto: {
             phase: string;
             /** @enum {string} */
@@ -13132,6 +13246,15 @@ export type ReadinessFixGuideDto = components['schemas']['ReadinessFixGuideDto']
 export type FixRetryableErrorCode = components['schemas']['FixRetryableErrorCode'];
 export type FixNonRetryableErrorCode = components['schemas']['FixNonRetryableErrorCode'];
 export type CreateFixRequestBodyDto = components['schemas']['CreateFixRequestBodyDto'];
+export type RulesSkillsAssessedTools = components['schemas']['RulesSkillsAssessedTools'];
+export type RulesSkillsValidateRequestDto = components['schemas']['RulesSkillsValidateRequestDto'];
+export type RulesSkillsFindingDto = components['schemas']['RulesSkillsFindingDto'];
+export type RulesSkillsSoftQualityCheckDto = components['schemas']['RulesSkillsSoftQualityCheckDto'];
+export type RulesSkillsSoftQualitySummaryDto = components['schemas']['RulesSkillsSoftQualitySummaryDto'];
+export type RulesSkillsProposedFileDto = components['schemas']['RulesSkillsProposedFileDto'];
+export type RulesSkillsValidateResponseDto = components['schemas']['RulesSkillsValidateResponseDto'];
+export type RulesSkillsOpenPullRequestRequestDto = components['schemas']['RulesSkillsOpenPullRequestRequestDto'];
+export type RulesSkillsOpenPullRequestResponseDto = components['schemas']['RulesSkillsOpenPullRequestResponseDto'];
 export type PhaseRoleDto = components['schemas']['PhaseRoleDto'];
 export type SquadMemberDto = components['schemas']['SquadMemberDto'];
 export type CustomWorkStreamTaskDto = components['schemas']['CustomWorkStreamTaskDto'];
@@ -22868,6 +22991,134 @@ export interface operations {
             };
         };
     };
+    postRulesSkillsValidate: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                workspaceId: components["parameters"]["WorkspaceId"];
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["RulesSkillsValidateRequestDto"];
+            };
+        };
+        responses: {
+            /** @description Validation result with findings and draft proposed files */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["RulesSkillsValidateResponseDto"];
+                };
+            };
+            /** @description Invalid body (e.g. malformed repoId) */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorMessageDto"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            /** @description Workspace or repository not found / not connected */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorMessageDto"];
+                };
+            };
+            /** @description No succeeded readiness scan for the repo (`code: readiness_scan_required`), or repository is not a GitHub-connected readiness repo. */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorMessageDto"];
+                };
+            };
+            /** @description Clone or GitHub App configuration failed */
+            503: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorMessageDto"];
+                };
+            };
+        };
+    };
+    postRulesSkillsPullRequest: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                workspaceId: components["parameters"]["WorkspaceId"];
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["RulesSkillsOpenPullRequestRequestDto"];
+            };
+        };
+        responses: {
+            /** @description Pull request created */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["RulesSkillsOpenPullRequestResponseDto"];
+                };
+            };
+            /** @description Missing proposed files or invalid body (`code: proposed_files_required`). */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorMessageDto"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            /** @description Workspace or repository not found */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorMessageDto"];
+                };
+            };
+            /** @description GitHub installation lacks write permissions required for automated PRs */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["GithubWritePermissionsRequiredErrorDto"];
+                };
+            };
+            /** @description GitHub installation permissions could not be verified, or PR create failed */
+            503: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["GithubPermissionsCheckFailedErrorDto"] | components["schemas"]["ErrorMessageDto"];
+                };
+            };
+        };
+    };
     getReadinessIssueFixGuide: {
         parameters: {
             query?: never;