work

docs/advisory-ai/cli.md

@@ -0,0 +1,70 @@
+# Advisory AI CLI Usage (DOCS-AIAI-31-005)
+
+_Updated: 2025-11-24 · Owners: Docs Guild · DevEx/CLI Guild · Sprint 0111_
+
+This guide shows how to drive Advisory AI from the StellaOps CLI using the `advise run` verb, with deterministic fixtures published on 2025-11-19 (`CLI-VULN-29-001`, `CLI-VEX-30-001`). It is designed for CI/offline use and mirrors the guardrail/policy contracts captured in `docs/advisory-ai/guardrails-and-evidence.md` and `docs/policy/assistant-parameters.md`.
+
+## Prerequisites
+- CLI binary from Sprint 205 (`stella`), logged in with scopes `advisory-ai:operate` + `aoc:verify`.
+- Base URL pointed at Advisory AI gateway: `export STELLAOPS_ADVISORYAI_URL=https://advisory-ai.internal` (falls back to main backend base address when unset).
+- Evidence fixtures available locally (offline friendly):
+  - `out/console/guardrails/cli-vuln-29-001/sample-vuln-output.ndjson` (SHA256 `e5aecfba5cee8d412408fb449f12fa4d5bf0a7cb7e5b316b99da3b9019897186`).
+  - `out/console/guardrails/cli-vuln-29-001/sample-sbom-context.json` (SHA256 `421af53f9eeba6903098d292fbd56f98be62ea6130b5161859889bf11d699d18`).
+  - `out/console/guardrails/cli-vex-30-001/sample-vex-output.ndjson` (SHA256 `2b11b1e2043c2ec1b0cb832c29577ad1c5cbc3fbd0b379b0ca0dee46c1bc32f6`).
+- Policy hash pinned: set `ADVISORYAI__POLICYVERSION=2025.11.19` (or the bundle hash shipped in the Offline Kit).
+
+## Quickstart
+```bash
+stella advise run summary \
+  --advisory-key csaf:redhat:RHSA-2025:1001 \
+  --artifact-id registry.stella-ops.internal/runtime/api \
+  --policy-version "$ADVISORYAI__POLICYVERSION" \
+  --profile fips-local \
+  --timeout 30 \
+  --json
+```
+- Use `--timeout 0` for cache-only probes in CI; add `--force-refresh` to bypass cache.
+- `--profile cloud-openai` remains disabled unless tenant consent is recorded in Authority; guardrails reject with exit code 12 when disabled.
+- Guardrail fixtures (`sample-vuln-output.ndjson`, `sample-vex-output.ndjson`, `sample-sbom-context.json`) live in Offline Kits and feed the backend self-tests; the CLI fetches evidence from backend services automatically.
+
+## Exit codes
+| Code | Meaning | Notes |
+| --- | --- | --- |
+| 0 | Success (hit or miss; output cached or freshly generated) | Includes `outputHash` and citations. |
+| 2 | Validation error (missing advisory key, bad profile) | Mirrors HTTP 400.
+| 3 | Context unavailable (SBOM/LNM/policy missing) | Mirrors HTTP 409 `advisory.contextUnavailable`.
+| 4 | Guardrail block (PII, citation gap, prompt too large) | Mirrors HTTP 422 `advisory.guardrail.blocked`.
+| 5 | Timeout waiting for output | Respect `--timeout` in seconds (0 = no wait). |
+| 12 | Remote profile disabled | Returned when `cloud-openai` is selected without consent. |
+| 7 | Transport/auth failure | Network/TLS/token issues. |
+
+## Scripting patterns
+- **Cache-only probes (CI smoke):** `stella advise run summary --advisory-key ... --timeout 0 --json > cache.json` (fails fast if evidence missing).
+- **Batch mode:** pipe advisory keys: `cat advisories.txt | xargs -n1 -I{} stella advise run summary --advisory-key {} --timeout 0 --json`.
+- **Profile gating:** set `--profile fips-local` for offline; use `--profile cloud-openai` only after Authority consent and when `ADVISORYAI__INFERENCE__MODE=Remote`.
+- **Policy pinning:** always pass `--policy-version` (matches Offline Kit bundle hash); outputs include the policy hash in `context.planCacheKey`.
+
+## Sample output (trimmed)
+```json
+{
+  "taskType": "Summary",
+  "profile": "fips-local",
+  "generatedAt": "2025-11-24T00:00:00Z",
+  "outputHash": "sha256:cafe...babe",
+  "citations": [{"index":1,"kind":"advisory","sourceId":"concelier:csaf:redhat:RHSA-2025:1001:paragraph:12"}],
+  "context": {
+    "planCacheKey": "adv-summary:csaf:redhat:RHSA-2025:1001:fips-local",
+    "sbom": {"artifactId":"registry.stella-ops.internal/runtime/api","versionTimeline":8,"dependencyPaths":5}
+  }
+}
+```
+
+## Offline kit notes
+- Copy the three CLI guardrail artefact bundles and their `hashes.sha256` files into `offline-kit/advisory-ai/fixtures/` and record them in `SHA256SUMS`.
+- Set `ADVISORYAI__SBOM__BASEADDRESS` to the SBOM Service endpoint packaged in the kit; leave unset to fall back to `NullSbomContextClient` (Advisory AI will still respond deterministically with context counts set to 0).
+- Keep `profiles.catalog.json` and `prompts.manifest` hashes aligned with the guardrail pack referenced in the Offline Kit manifest.
+
+## Troubleshooting
+- `contextUnavailable`: ensure SBOM service is reachable or provide `--sbom-context` fixture; verify LNM linkset IDs and hashes.
+- `guardrail.blocked`: check blocked phrase list (`docs/policy/assistant-parameters.md`) and payload size; remove PII or reduce SBOM clamps.
+- `timeout`: raise `--timeout` or run cache-only mode to avoid long waits in CI.

docs/advisory-ai/evidence-payloads.md

@@ -1,8 +1,8 @@
 # Advisory AI Evidence Payloads (LNM-Aligned)
 
-_Updated: 2025-11-18 · Owner: Advisory AI Docs Guild · Sprint: 0111 (AIAI-RAG-31-003)_
+_Updated: 2025-11-24 · Owner: Advisory AI Docs Guild · Sprint: 0111 (AIAI-RAG-31-003)_
 
-This document defines how Advisory AI consumes Link-Not-Merge (LNM) observations and linksets for Retrieval-Augmented Generation (RAG). It aligns payloads with the frozen LNM v1 schema (`docs/modules/concelier/link-not-merge-schema.md`, 2025-11-17) and replaces prior draft payloads. CLI/Policy artefacts (`CLI-VULN-29-001`, `CLI-VEX-30-001`, `policyVersion` digests) are referenced but optional at runtime; missing artefacts trigger deterministic `409 advisory.contextUnavailable` responses rather than fallback merging.
+This document defines how Advisory AI consumes Link-Not-Merge (LNM) observations and linksets for Retrieval-Augmented Generation (RAG). It aligns payloads with the frozen LNM v1 schema (`docs/modules/concelier/link-not-merge-schema.md`, 2025-11-17) and replaces prior draft payloads. CLI/Policy artefacts (`CLI-VULN-29-001`, `CLI-VEX-30-001`, `policyVersion` digests) are referenced but optional at runtime; missing artefacts trigger deterministic `409 advisory.contextUnavailable` responses rather than fallback merging. A deterministic SBOM context fixture lives at `out/console/guardrails/cli-vuln-29-001/sample-sbom-context.json` (SHA256 `421af53f9eeba6903098d292fbd56f98be62ea6130b5161859889bf11d699d18`) and is used in the examples below.
 
 ## 1) Input envelope (per task)
 

docs/advisory-ai/guardrails-and-evidence.md

@@ -1,15 +1,16 @@
 # Advisory AI Guardrails & Evidence Intake
 
-_Updated: 2025-11-22 · Owner: Advisory AI Docs Guild · Status: Draft (Sprint 0111)_
+_Updated: 2025-11-24 · Owner: Advisory AI Docs Guild · Status: Published (Sprint 0111)_
 
 This note captures the guardrail behaviors and evidence intake boundaries required by Sprint 0111 tasks (`AIAI-DOCS-31-001`, `AIAI-RAG-31-003`). It binds Advisory AI guardrails to upstream evidence sources and clarifies how Link-Not-Merge (LNM) documents flow into Retrieval-Augmented Generation (RAG) payloads.
 
 ## 1) Evidence sources and contracts
 
-**Upstream readiness gates**
+**Upstream readiness gates (now satisfied)**
 
-- CLI + Policy artefacts (`CLI-VULN-29-001`, `CLI-VEX-30-001`, `policyVersion` digests) must be present before enabling non-default profiles. Until then, Advisory AI accepts requests but responds with `409 advisory.contextUnavailable` when those references are missing.
-- LNM linksets stay the single source of truth; Advisory AI refuses ad-hoc advisory payloads even if CLI/Policy artefacts are delayed.
+- CLI guardrail artefacts landed on 2025-11-19: `out/console/guardrails/cli-vuln-29-001/` (`sample-vuln-output.ndjson`, `sample-sbom-context.json`) and `out/console/guardrails/cli-vex-30-001/` (`sample-vex-output.ndjson`). Hashes are recorded in `docs/modules/cli/artefacts/guardrails-artefacts-2025-11-19.md` and must be copied into Offline Kits.
+- Policy hash must be pinned (`policyVersion`, see `docs/policy/assistant-parameters.md`) before enabling non-default profiles.
+- LNM linksets stay the single source of truth; Advisory AI refuses ad-hoc advisory payloads even if upstream artefacts drift.
 
 - **Advisory observations (LNM)** — Consume immutable `advisory_observations` and `advisory_linksets` produced per `docs/modules/concelier/link-not-merge-schema.md` (frozen v1, 2025-11-17).
 - **VEX statements** — Excititor + VEX Lens linksets with trust weights; treated as structured chunks with `source_id` and `confidence`.
@@ -63,5 +64,6 @@ See `docs/advisory-ai/evidence-payloads.md` for full JSON examples and alignment
 - [ ] LNM feed enabled and Concelier schemas at v1 (2025-11-17).
 - [ ] SBOM retriever configured or `NullSbomContextClient` left as safe default.
 - [ ] Policy hash pinned via `policyVersion` when reproducibility is required.
+- [ ] CLI guardrail artefact hashes verified against `docs/modules/cli/artefacts/guardrails-artefacts-2025-11-19.md` and mirrored into Offline Kits.
 - [ ] Remote profiles only after Authority consent and profile allowlist are set.
 - [ ] Cache directories shared between web + worker hosts for DSSE sealing.

docs/advisory-ai/sbom-context-hand-off.md

@@ -0,0 +1,55 @@
+# SBOM Context Hand-off for Advisory AI (SBOM-AIAI-31-003)
+
+_Updated: 2025-11-24 · Owners: Advisory AI Guild · SBOM Service Guild · Sprint 0111_
+
+Defines the contract and smoke test for passing SBOM context from SBOM Service to Advisory AI `/v1/sbom/context` consumers. Aligns with `SBOM-AIAI-31-001` (paths/timelines) and the CLI fixtures published on 2025-11-19.
+
+## Contract
+- **Endpoint** (SBOM Service): `/sbom/context`
+- **Request** (minimal):
+```json
+{
+  "artifactId": "registry.stella-ops.internal/runtime/api",
+  "purl": "pkg:oci/runtime-api@sha256:d2c3...",
+  "timelineClamp": 500,
+  "dependencyPathClamp": 200
+}
+```
+- **Response** (summarised):
+```json
+{
+  "schema": "stellaops.sbom.context/1.0",
+  "generated": "2025-11-19T00:00:00Z",
+  "packages": [
+    {"name":"openssl","version":"1.1.1w","purl":"pkg:deb/openssl@1.1.1w"},
+    {"name":"zlib","version":"1.2.11","purl":"pkg:deb/zlib@1.2.11"}
+  ],
+  "timeline": 8,
+  "dependencyPaths": 5,
+  "hash": "sha256:421af53f9eeba6903098d292fbd56f98be62ea6130b5161859889bf11d699d18"
+}
+```
+- **Determinism**: clamp values fixed unless overridden; `generated` timestamp frozen per fixture when offline.
+- **Headers**: `X-StellaOps-Tenant` required; `X-StellaOps-ApiKey` optional for bootstrap.
+
+## Smoke test (tenants/offline)
+1. Start SBOM Service with fixture data loaded (or use `sample-sbom-context.json`).
+2. Run: `curl -s -H "X-StellaOps-Tenant: demo" -H "Content-Type: application/json" \
+   -d @out/console/guardrails/cli-vuln-29-001/sample-sbom-context.json \
+   http://localhost:8080/sbom/context | jq .hash` (expect `sha256:421a...9d18`).
+3. Configure Advisory AI:
+   - `AdvisoryAI:SBOM:BaseAddress=http://localhost:8080`
+   - `AdvisoryAI:SBOM:ApiKey=<key-if-required>`
+4. Call Advisory AI cache-only: `stella advise run remediation --advisory-key csaf:redhat:RHSA-2025:1001 --artifact-id registry.stella-ops.internal/runtime/api --timeout 0 --json`.
+   - Expect exit 0 and `sbomSummary.dependencyPaths=5` in response.
+5. Record the hash and endpoint in ops log; mirror fixture + hashes into Offline Kit under `offline-kit/advisory-ai/fixtures/sbom-context/`.
+
+## Failure modes
+- `409 advisory.contextHashMismatch` — occurs when the returned `hash` differs from the LNM linkset `provenanceHash`; refresh context or re-export.
+- `403` — tenant/api key mismatch; check `X-StellaOps-Tenant` and API key.
+- `429` — clamp exceeded; reduce `timelineClamp`/`dependencyPathClamp` or narrow `artifactId`.
+
+## References
+- `docs/sbom/remediation-heuristics.md` (blast-radius scoring).
+- `docs/advisory-ai/guardrails-and-evidence.md` (evidence contract).
+- `docs/modules/cli/artefacts/guardrails-artefacts-2025-11-19.md` (hashes for fixtures).