up
This commit is contained in:
StellaOps Bot
@@ -119,4 +119,3 @@
|
||||
- Replay/cache/entropy contracts frozen in `docs/modules/scanner/design/` (replay-pipeline-contract.md, cache-key-contract.md, entropy-transport.md).
|
||||
- SPDX 3.0.1 scope executed under Sbomer; any future changes require new sprint.
|
||||
- Determinism harness and release publication align with `docs/modules/scanner/determinism-score.md`; keep harness inputs stable to avoid drift.
|
||||
|
||||
|
||||
63
docs/implplan/archived/SPRINT_0511_0001_0001_api.md
Normal file
63
docs/implplan/archived/SPRINT_0511_0001_0001_api.md
Normal file
@@ -0,0 +1,63 @@
|
||||
# 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-10) | Notification templates + deprecation schema delivered; changelog/compat outputs include notification signals. | 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-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 + Notification templates now wired; notification signals included in changelog/compat outputs.
|
||||
|
||||
## Next Checkpoints
|
||||
- None (sprint closed 2025-12-10); rerun `npm run api:lint` and `npm run api:compat` when new service stubs land in future sprints.
|
||||
Reference in New Issue
Block a user