.specify/features/_example/api-contract.yaml

@@ -45,6 +45,7 @@ paths:
   /api/users/me/avatar:
     post:
       summary: Upload or replace the current user's avatar
+      tags: [Users]
       operationId: uploadMyAvatar
       security:
         - cookieAuth: []
@@ -78,6 +79,7 @@ paths:
               schema: { $ref: '#/components/schemas/ErrorResponse' }
     delete:
       summary: Remove the current user's avatar
+      tags: [Users]
       operationId: deleteMyAvatar
       security:
         - cookieAuth: []
@@ -95,6 +97,7 @@ paths:
   /api/users/{id}/avatar:
     get:
       summary: Stream a user's avatar image (authenticated proxy)
+      tags: [Users]
       operationId: getUserAvatar
       security:
         - cookieAuth: []
@@ -113,6 +116,7 @@ paths:
         '404': { description: User has no avatar, content: { application/json: { schema: { $ref: '#/components/schemas/ErrorResponse' } } } }
     delete:
       summary: Remove another user's avatar (admin only)
+      tags: [Users]
       operationId: deleteUserAvatar
       description: Requires Permission.ADMIN_USER (enforced by @RequirePermission on the controller).
       security:

.specify/templates/api-contract-stub.md

@@ -86,11 +86,12 @@ paths:
 
 ## Validating the contract in CI
 
-The `sdd-gate.yml` workflow runs, on PRs that touch a `api-contract.yaml`:
+The `sdd-gate.yml` `contract-validate` job lints any committed OpenAPI file changed in the PR:
 
 ```bash
-npx @stoplight/spectral-cli lint .specify/features/**/api-contract.yaml
+npx @stoplight/spectral-cli lint <your-contract>.yaml
 ```
 
-Spectral's default OpenAPI ruleset catches malformed specs, missing `operationId`s, and
-undefined `$ref`s. Add a `.spectral.yaml` at the repo root to tune rules if needed.
+The ruleset is `.spectral.yaml` at the repo root (extends `spectral:oas`; documentation-only
+warnings relaxed for design-time stubs). Spectral auto-discovers it. It catches malformed
+specs, undefined `$ref`s, and duplicate `operationId`s; tune `.spectral.yaml` to adjust.

.spectral.yaml

@@ -0,0 +1,15 @@
+# Spectral ruleset for OpenAPI contract linting (SDD api-contract files).
+# Spectral v6 ships no implicit ruleset — this enables the built-in OpenAPI rules.
+# Used by .gitea/workflows/sdd-gate.yml (contract-validate) and locally:
+#   npx @stoplight/spectral-cli lint <contract>.yaml
+extends: ["spectral:oas"]
+
+rules:
+  # Design-time SDD stubs are not full published API docs — relax the documentation-completeness
+  # warnings that would otherwise fire on a focused contract. The structural/correctness rules
+  # (oas3-schema, valid $refs, duplicate operationId, etc.) stay on.
+  info-contact: off
+  info-description: off
+  operation-description: off
+  operation-tag-defined: off
+  oas3-unused-component: off