2eaf0f699b
Some checks failed
AOC Guard CI / aoc-guard (push) Has been cancelled
AOC Guard CI / aoc-verify (push) Has been cancelled
Concelier Attestation Tests / attestation-tests (push) Has been cancelled
Docs CI / lint-and-preview (push) Has been cancelled
devportal-offline / build-offline (push) Has been cancelled
Mirror Thin Bundle Sign & Verify / mirror-sign (push) Has been cancelled
- Added AirgapTimelineImpact, AirgapTimelineImpactInput, and AirgapTimelineImpactResult records for managing air-gap bundle import impacts. - Introduced EvidenceSnapshotRecord, EvidenceSnapshotLinkInput, and EvidenceSnapshotLinkResult records for linking findings to evidence snapshots. - Created IEvidenceSnapshotRepository interface for managing evidence snapshot records. - Developed StalenessValidationService to validate staleness and enforce freshness thresholds. - Implemented AirgapTimelineService for emitting timeline events related to bundle imports. - Added EvidenceSnapshotService for linking findings to evidence snapshots and verifying their validity. - Introduced AirGapOptions for configuring air-gap staleness enforcement and thresholds. - Added minimal jsPDF stub for offline/testing builds in the web application. - Created TypeScript definitions for jsPDF to enhance type safety in the web application.
6.9 KiB
6.9 KiB
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).
- APIGOV-63-001 blocked on Notification Studio templates and deprecation metadata schema.
Documentation Prerequisites
- docs/modules/ci/architecture.md
- docs/api/openapi-discovery.md
- src/Api/StellaOps.Api.Governance/README.md (if present)
BLOCKED Tasks: Before working on BLOCKED tasks, review BLOCKED_DEPENDENCY_TREE.md for root blockers and dependencies.
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 | BLOCKED | Missing Notification Studio templates + deprecation schema | 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-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
- APIGOV-63-001 blocked until Notification Studio templates and deprecation metadata schema are delivered; downstream changelog/compat outputs must note missing notification metadata.
- 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.
Next Checkpoints
- Receive Notification Studio templates/deprecation schema to unblock APIGOV-63-001 and add notification examples.
- Re-run
npm run api:lintandnpm run api:compatafter next service stub additions to refresh baseline and changelog artifacts.