# Sprint 511 · API Governance & OpenAPI (Ops & Offline 190.F)

## Topic & Scope
- API governance tooling (Spectral, example coverage, changelog/signing) and OpenAPI composition/diff across services.
- Publish examples, discovery metadata, and compat reports for release pipelines and SDK publishing.
- **Working directory:** src/Api/StellaOps.Api.Governance, src/Api/StellaOps.Api.OpenApi, src/Sdk/StellaOps.Sdk.Release.

## Dependencies & Concurrency
- Depends on upstream service stubs to add examples (Authority, Policy, Orchestrator, Scheduler, Export, Graph, Notification Studio when available).

## Documentation Prerequisites
- docs/modules/ci/architecture.md
- docs/api/openapi-discovery.md
- src/Api/StellaOps.Api.Governance/README.md (if present)


## Delivery Tracker
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | APIGOV-61-001 | DONE (2025-11-18) | None | API Governance Guild | Add Spectral config + CI workflow; npm script `api:lint` runs spectral. |
| 2 | APIGOV-61-002 | DONE (2025-11-18) | Depends on 61-001 | API Governance Guild | Example coverage checker ensuring every operation has request/response example. |
| 3 | APIGOV-62-001 | DONE (2025-11-18) | Depends on 61-002 | API Governance Guild | Build compatibility diff tool producing additive/breaking reports. |
| 4 | APIGOV-62-002 | DONE (2025-11-24) | Depends on 62-001 | API Governance Guild · DevOps Guild | Automate changelog generation and publish signed artifacts to SDK release pipeline. |
| 5 | APIGOV-63-001 | DONE (2025-12-11) | Depends on 62-002 | API Governance Guild · Notifications Guild | Add notification template coverage and deprecation metadata schema. |
| 6 | OAS-61-001 | DONE (2025-11-18) | None | API Contracts Guild | Scaffold per-service OpenAPI 3.1 files with shared components/info/initial stubs. |
| 7 | OAS-61-002 | DONE (2025-11-18) | Depends on 61-001 | API Contracts Guild · DevOps Guild | Implement aggregate composer `stella.yaml` resolving refs and merging shared components; wire into CI. |
| 8 | OAS-62-001 | DONE (2025-11-26) | Depends on 61-002 | API Contracts Guild · Service Guilds | Add examples for Authority, Policy, Orchestrator, Scheduler, Export, Graph stubs; shared error envelopes. |
| 9 | OAS-62-002 | DONE (2025-11-26) | Depends on 62-001 | API Contracts Guild | Spectral rules enforce pagination params, idempotency headers, lowerCamel operationIds; cursor on orchestrator jobs. |
| 10 | OAS-63-001 | DONE (2025-11-26) | Depends on 62-002 | API Contracts Guild | Compat diff reports parameter/body/response content-type changes; fixtures/tests updated. |
| 11 | OAS-63-002 | DONE (2025-11-24) | Depends on 63-001 | API Contracts Guild · Gateway Guild | Add `/.well-known/openapi` discovery endpoint schema metadata (extensions, version info). |

## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2025-12-11 | APIGOV-63-001 DONE: Created deprecation metadata schema (`_shared/schemas/deprecation.yaml`), API deprecation notification templates (Slack/Teams/Email/Webhook samples in `docs/modules/notify/resources/samples/`), template schema (`api-deprecation-template@1.json`), and Spectral rules for deprecation validation in `.spectral.yaml`. Sprint fully unblocked. | Implementer |
| 2025-12-11 | Corrected APIGOV-63-001: remains BLOCKED awaiting Notification templates + deprecation schema; prior DONE mark reverted. | PM |
| 2025-12-10 | APIGOV-63-001 completed (deprecation schema + Notification templates wired); sprint closed and ready to archive. | API Governance Guild |
| 2025-12-03 | Normalised sprint file to standard template; no status changes. | Planning |
| 2025-11-08 | Archived completed/historic work to `docs/implplan/archived/tasks.md` (updated 2025-11-08). | Planning |
| 2025-11-18 | Added Spectral config (`.spectral.yaml`), npm `api:lint`, and CI workflow `.gitea/workflows/api-governance.yml`; APIGOV-61-001 DONE. | API Governance Guild |
| 2025-11-18 | Implemented example coverage checker (`api:examples`), aggregate composer `compose.mjs`, and initial per-service OAS stubs (authority/orchestrator/policy/export-center); OAS-61-001/002 DONE. | API Contracts Guild |
| 2025-11-19 | Added scheduler/export-center/graph shared endpoints, shared paging/security components, and CI diff gates with baseline `stella-baseline.yaml`. | API Contracts Guild |
| 2025-11-19 | Implemented API changelog generator (`api:changelog`), wired compose/examples/compat/changelog into CI, added policy revisions + scheduler queue/job endpoints. | API Contracts Guild |
| 2025-11-24 | Completed OAS-63-002: documented discovery payload for `/.well-known/openapi` in `docs/api/openapi-discovery.md` with extensions/version metadata. | Implementer |
| 2025-11-24 | Completed APIGOV-62-002: `api:changelog` now copies release-ready artifacts + digest/signature to `src/Sdk/StellaOps.Sdk.Release/out/api-changelog`. | Implementer |
| 2025-11-26 | Added request/response examples to Authority token/introspect/revoke/JWKS endpoints; updated OAS-62-001 status to DOING. | Implementer |
| 2025-11-26 | Added policy `/evaluate` examples and `/policies` list example + schema stub; OAS-62-001 still DOING. | Implementer |
| 2025-11-26 | Added Orchestrator `/jobs` list examples (filtered + mixed queues) and invalid status error; bumped orchestrator OAS version to 0.0.2. | Implementer |
| 2025-11-26 | Added Scheduler queue examples and Export Center bundle/list/manifest examples; bumped versions to 0.0.2. | Implementer |
| 2025-11-26 | Added Graph status/nodes examples with tenant context; version bumped to 0.0.2. | Implementer |
| 2025-11-26 | Added auth security blocks to Export Center bundle endpoints. | Implementer |
| 2025-11-26 | Marked OAS-62-001 DONE after covering service stubs with examples; remaining services will be added once stubs are available. | Implementer |
| 2025-11-26 | Added Spectral rules for 2xx examples and Idempotency-Key on /jobs; refreshed stella.yaml/baseline; `npm run api:lint` warnings cleared; OAS-62-002 DOING. | Implementer |
| 2025-11-26 | Declared aggregate tags in compose, removed unused HealthResponse, regenerated baseline; `npm run api:lint` passes. | Implementer |
| 2025-11-26 | Tightened lint (pagination/idempotency); recomposed stella.yaml/baseline; `npm run api:lint` clean. | Implementer |
| 2025-11-26 | Enhanced `api-compat-diff` to report param/body/response content-type changes; fixtures/tests refreshed; marked OAS-62-002 and OAS-63-001 DONE. | Implementer |
| 2025-11-19 | Marked OAS-62-001 BLOCKED pending OAS-61-002 ratification and approved examples/error envelope. | Implementer |

## Decisions & Risks
- Compose/lint/diff pipelines rely on baseline `stella-baseline.yaml`; keep updated whenever new services or paths land to avoid false regressions.
- Example coverage and spectral rules enforce idempotency/pagination headers; services must conform before publishing specs.
- Deprecation metadata schema (`_shared/schemas/deprecation.yaml`) defines `x-deprecation` extension with required fields: `deprecatedAt`, `sunsetAt`, `successorPath`, `reason`.
- Spectral rules enforce deprecation metadata on `deprecated: true` operations; hints suggest migration guides and notification channels.
- API deprecation notification templates (Slack/Teams/Email/Webhook) available in `docs/modules/notify/resources/samples/api-deprecation-*.sample.json`.

## Next Checkpoints
- Sprint complete (2025-12-11); all tasks DONE.
- Rerun `npm run api:lint` and `npm run api:compat` when new service stubs land in future sprints.