up

docs/contributing/api-contracts.md

@@ -1,37 +1,58 @@
-# API Contract Contribution Guide
+# Contributing to API Contracts
 
-This guide explains how to propose, review, and publish API contract changes across StellaOps services. Follow these steps whenever you modify an OpenAPI specification or an externally supported endpoint.
+Last updated: 2025-11-25
 
-## 1. Background
+## Scope
+Guidelines for editing service OpenAPI specs, lint rules, compatibility checks, and release artefacts across StellaOps services.
 
-- Public APIs are defined in `src/Api/StellaOps.Api.OpenApi` (aggregate spec) and per-service OpenAPI documents.
-- Compatibility checks run in CI via the API Governance tooling (`StellaOps.Api.Governance`).
-- Docs & SDK guilds consume the generated specs to publish references and SDK packages.
+## Required tools
+- Node.js 20.x + pnpm 9.x
+- Spectral CLI (invoked via `pnpm api:lint` in `src/Api/StellaOps.Api.OpenApi`)
+- `diff2html` (optional) for human-friendly compat reports
 
-## 2. Workflow
+## Workflow (per change)
+1) Edit service OAS under `src/Api/StellaOps.Api.OpenApi/services/<service>/*.yaml`.
+2) Run lint + compose + compat + changelog from repo root:
+   ```bash
+   pnpm --filter @stella/api-openapi api:lint       # spectral
+   pnpm --filter @stella/api-openapi api:compose    # build stella.yaml
+   pnpm --filter @stella/api-openapi api:compat     # compare against baseline
+   pnpm --filter @stella/api-openapi api:changelog  # generate digest/signature
+   ```
+3) Review outputs:
+   - `out/api/stella.yaml` (composed spec)
+   - `out/api/compat-report.json` (+ `.html` if generated)
+   - `out/api/changelog/` (digest + signature for SDK pipeline)
+4) Update examples: ensure request/response examples exist for changed endpoints; add to `examples/` directories.
+5) Commit changes with notes on breaking/additive results; attach compat report paths.
 
-1. **Design review** – capture the proposed endpoint or schema change in the relevant module’s `TASKS.md` and link to any ADR or design doc.
-2. **Spec update** – modify the service-specific OpenAPI file under `src/Api/StellaOps.Api.OpenApi/<service>/`.
-3. **Run governance checks** – execute `dotnet test src/Api/StellaOps.Api.Governance.Tests` to validate lint rules, backwards compatibility, and examples.
-4. **Regenerate aggregate spec** – run `dotnet run --project src/Api/StellaOps.Api.OpenApi` to update `stella.yaml`.
-5. **Update docs** – adjust the corresponding module dossier (`docs/modules/<component>/architecture.md` or guides) to reflect new/changed endpoints.
-6. **Notify SDK/Docs guilds** – coordinate SDK regeneration (`src/Sdk/StellaOps.Sdk.Generator`) and release notes.
+## Lint rules (Spectral)
+- House rules live in `.spectral.yaml` under `src/Api/StellaOps.Api.OpenApi`.
+- Enforce: tagged operations, error envelope shape, schema refs reuse, pagination tokens, RBAC scopes, standard headers (`traceparent`, `x-correlation-id`).
 
-## 3. Backwards Compatibility Rules
+## Compatibility checks
+- Baseline file: `stella-baseline.yaml` (kept in repo under `out/api/` and updated per release).
+- `api:compat` flags additive/breaking/unchanged deltas. Breaking changes require approval from API Governance Guild and affected service guilds.
 
-- Avoid breaking changes (removing endpoints/fields, altering semantics). If unavoidable, document deprecation timelines and fallback behaviour.
-- Additive changes (new optional fields, new endpoints) require version bump and changelog entry.
-- Error responses must remain structured; return `application/problem+json` payloads with stable error codes.
+## Examples & error envelopes
+- Every operation must have at least one request + response example.
+- Error responses must use the standard envelope (`error.code`, `error.message`, `trace_id`).
 
-## 4. Tooling
+## Offline/air-gap
+- Keep `pnpm-lock.yaml` pinned; store `node_modules/.pnpm` cache in Offline Kit when needed.
+- Include composed spec, compat report, and changelog artefacts in offline bundles under `offline/api/` with checksums.
 
-- `dotnet tool run stellaops-api-lint` – local lint.
-- `dotnet run --project src/Api/StellaOps.Api.OpenApi -- --validate` – schema validation.
-- `docs/09_API_CLI_REFERENCE.md` – update CLI reference when command behaviour shifts.
+## Release handoff
+- Deliverables for each release:
+  - `out/api/stella.yaml`
+  - `out/api/compat-report.json` (+ `.html` if produced)
+  - `out/api/changelog/*` (digest, signature, manifest)
+- Provide SHA256 checksums for artefacts and note `source_commit` + `timestamp` in release notes.
 
-## 5. References
-
-- `docs/modules/platform/architecture-overview.md`
-- `docs/modules/cli/architecture.md`
-- `src/Api/StellaOps.Api.Governance`
-- `src/Api/StellaOps.Api.OpenApi`
+## Review checklist
+- [ ] Lint clean (`api:lint`)
+- [ ] Examples present for changed endpoints
+- [ ] Compat report reviewed (additive/breaking noted)
+- [ ] Changelog artefacts generated + checksums
+- [ ] Offline bundle artefacts staged (if required)
+- [ ] Docs/UI/SDK owners notified of breaking changes