ci(spec): enforce WAVE redocly ruleset on openapi.yaml

[yakimoto]

North Star Card L6 (CONTRACT) lever. The existing foundation-gate spec-lint job runs bare redocly; this adds redocly.yaml which that job auto-loads, enforcing: operation-summary (error), kebab-case path segments (error), operation-4xx-response (warn, backlog visible). Verified: redocly lint exits 0 on the current spec.

---

Note

Low Risk
CI-only OpenAPI lint configuration with no runtime or API behavior changes; severities are tuned so the current spec still passes.

Overview
Adds .redocly.yaml so the existing foundation-gate spec-lint job (bare redocly lint openapi.yaml) picks up a WAVE ruleset instead of default-only linting.

The config extends recommended and sets operation-summary and a custom path-segments-kebab-case rule to error, while operation-4xx-response stays at warn so missing 4xx/5xx docs remain visible in CI without failing the gate until the backlog is fixed. Comments document that severities should tighten over time by fixing openapi.yaml, not loosening rules.

^{Reviewed by Cursor Bugbot for commit f508c94. Configure here.}

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is enabled.}

Note

Enforce WAVE Redocly ruleset on openapi.yaml via CI lint gate

Adds a redocly.yaml configuration that extends the recommended ruleset and enforces two additional rules: operation-summary (error) requires all operations to have summaries, and a custom rule/path-segments-kebab-case (error) enforces kebab-case path segments with brace-wrapped parameters. A third rule, operation-4xx-response, is set to warn only. Risk: existing OpenAPI operations without summaries or with non-kebab-case path segments will now fail CI.

^{Macroscope summarized 37d8ee2.}

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_f67a4617-43ab-45e5-9607-110e163cdff9)

[coderabbitai]

Warning

Review limit reached

You’ve reached a temporary PR review limit under our Fair Usage Limits Policy.

Your recent review volume is higher than typical usage, so adaptive limits are currently applied.

Next review available in: 2 minutes

Your organization has reached its usage spending cap. Adjust your spending cap in the billing tab.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: dfcc6052-af88-47ff-aa87-9b8855890679

📥 Commits

Reviewing files that changed from the base of the PR and between 6649096 and 37d8ee2.

📒 Files selected for processing (1)

• redocly.yaml

---

_{Comment @coderabbitai help to get the list of available commands.}

[qodo-code-review]

PR Summary by Qodo

Enforce WAVE Redocly rules via .redocly.yaml for OpenAPI lint gate

⚙️ Configuration changes ✨ Enhancement 🕐 Less than 10 minutes

AI Description

• Add a repository Redocly ruleset auto-loaded by the spec-lint CI job.
• Enforce operation summaries and kebab-case path segments as build-breaking errors.
• Surface missing 4xx/5xx responses as warnings to track backlog without failing CI.

Diagram

graph TD
  A["CI: spec-lint job"] --> B["redocly lint"] --> C["Lint result"]
  B --> D["openapi.yaml"]
  B --> E[".redocly.yaml ruleset"]

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Inline lint rules in CI command

• ➕ Rules are visible directly in the CI workflow definition
• ➕ Avoids adding repository-level tooling config
• ➖ Harder to version/review rule changes alongside spec edits
• ➖ Less discoverable for local linting (developers must mirror CI flags)

2. Adopt Spectral ruleset instead of Redocly rules

• ➕ Very flexible custom rules and ecosystem
• ➕ Can be shared across repos/org with a common rules package
• ➖ Tooling switch cost and potential drift from existing foundation-gate expectations
• ➖ Requires revalidating severity semantics and CI integration

Recommendation: Keep the .redocly.yaml approach: it leverages Redocly’s default config auto-loading so CI and local runs stay consistent, while allowing incremental tightening (warn→error) as the spec backlog is addressed.

Files changed (1) +31 / -0

Other (1) +31 / -0

.redocly.yamlAdd WAVE Redocly ruleset for OpenAPI lint enforcement +31/-0

Add WAVE Redocly ruleset for OpenAPI lint enforcement

• Introduces a repository-level Redocly configuration that extends the recommended ruleset. Enforces operation summaries and kebab-case path segments as errors, while keeping missing 4xx-response documentation as warnings to avoid failing CI until the backlog is addressed.

.redocly.yaml

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

Great, no issues found!

Qodo reviewed your code and found no material issues that require review

Tip of the day

💡 Did you know, you can group findings by type and pick your Finding display, from Minimal to Full

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[qodo-code-review]

Qodo Fixer

No findings are available for this PR yet. Findings appear here once Qodo has reviewed the PR.

[macroscopeapp]

Approvability

Verdict: Approved 37d8ee2

This PR adds CI linting configuration for the OpenAPI spec. The change is owned by the author, has no runtime impact, and is a standard CI/CD addition. The unresolved Medium finding about the regex pattern not supporting well-known URIs will block merge independently.

^{You can customize Macroscope's approvability policy. Learn more.}