From bbfc9b2c420b7ea8b4f4736828331641cc9bc0b7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kim=20Harjam=C3=A4ki?= Date: Wed, 8 Jul 2026 15:01:25 +0300 Subject: [PATCH] docs: connect NO-AZURE-deploy-lock context in README + add docs-as-code wiki tree - README: explicit paragraph tying the existing no-deploy claim to the workspace-wide NO-AZURE-deploy hard lock and cas-platform's bicep-ready-but-not-deployed status; freshness footer - wiki: Home, Architecture (request flow + deploy-lock posture), Operations, Decisions - Adds codex:generate-image placeholder per docs/VISION.md house style --- README.md | 12 ++++++++ docs/wiki/Architecture.md | 55 +++++++++++++++++++++++++++++++++++ docs/wiki/Decisions.md | 19 ++++++++++++ docs/wiki/Home.md | 38 ++++++++++++++++++++++++ docs/wiki/Operations.md | 61 +++++++++++++++++++++++++++++++++++++++ 5 files changed, 185 insertions(+) create mode 100644 docs/wiki/Architecture.md create mode 100644 docs/wiki/Decisions.md create mode 100644 docs/wiki/Home.md create mode 100644 docs/wiki/Operations.md diff --git a/README.md b/README.md index 3e8ba65..3c30127 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,12 @@ It runs a useful deterministic workflow locally, emits canonical [`cas-contracts This project does not use Classic Assistants APIs and does not deploy Azure resources. +Azure deployment is locked workspace-wide until a future milestone (the CAS workspace's +NO-AZURE-deploy hard lock). `cas-platform`, the deployment target this project's interface is +designed for, is maintained "bicep-ready" (linted, parameterized, pinned) per Phase 33 but is not +itself deployed. This repository's Foundry Next Gen adapter is exercised only through local runs +and CI's Docker health-check smoke test — never a live Azure deploy. + ## Run Locally Prerequisites: Python 3.12 and PowerShell. @@ -72,3 +78,9 @@ The image runs as a non-root user, listens on port `8080`, and provides `/health ## Security Report vulnerabilities through GitHub private vulnerability reporting. Do not include credentials or sensitive prompt data in issues. + +## Wiki + +For a docs-as-code wiki (Home, Architecture, Operations, Decisions), see [`docs/wiki/`](docs/wiki/Home.md). + + diff --git a/docs/wiki/Architecture.md b/docs/wiki/Architecture.md new file mode 100644 index 0000000..2902c5b --- /dev/null +++ b/docs/wiki/Architecture.md @@ -0,0 +1,55 @@ +# Architecture + +`cas-reference-product` implements a strictly typed request/response boundary using canonical +`cas-contracts` data structures, with interchangeable local and Foundry Next Gen agent adapters +behind the same `WorkflowAgentService` interface. + +```mermaid +flowchart TD + Client[Client] -->|"POST /api/v1/workflows\nPromptEnvelope"| FastAPI["FastAPI Server\napp.py"] + FastAPI --> Middleware["W3CTraceContextMiddleware\ntelemetry.py"] + Middleware --> Router[Workflow Router] + Router --> Orchestrator["WorkflowOrchestrator\nworkflow.py"] + Orchestrator --> AgentService{"WorkflowAgentService\nworkflow.py"} + AgentService -->|Local Config| LocalAgent[LocalWorkflowAgentService] + AgentService -->|Foundry Config| FoundryAgent[FoundryWorkflowAgentService] + FoundryAgent -->|Managed Identity| AzureAuth["DefaultAzureCredential\nidentity.py"] + AzureAuth -->|Responses API| AzureAI[Azure AI Projects API] + AzureAI -->|Invoke Agent| FoundryNextGen[Foundry Next Gen Agent] + LocalAgent -->|Deterministic Output| Orchestrator + FoundryAgent -->|Agent Output| Orchestrator + Orchestrator -->|"RunEvent"| Router + Router -->|200 OK| Client +``` + + + +## Components + +- **FastAPI web layer (`app.py`)** — exposes `/api/v1/workflows`, `/health/live`, + `/health/ready`; manages OpenTelemetry spans via `PromptEnvelope.correlationId`. +- **Telemetry (`telemetry.py`)** — `W3CTraceContextMiddleware` parses and propagates + `traceparent`/`tracestate` headers. +- **Workflow Orchestrator (`workflow.py`)** — wraps agent execution, emits canonical `RunEvent` + data points (`workflow.started`, `workflow.completed`, `workflow.failed`). +- **Workflow Agent Service** — the application boundary for AI logic, with local (deterministic) + and Foundry Next Gen (managed-identity, Responses API) adapters behind one interface. + +## Deployment lock (NO-AZURE posture) + +This project does not use Classic Assistants APIs and does not deploy Azure resources. Azure +deployment is locked workspace-wide until a future milestone is deliberately reached — no +service under this workspace may be provisioned or deployed from here. `cas-platform`, the +Container Apps target this repo's interface (`deployment/cas-platform.interface.yaml`) is built +for, is maintained "bicep-ready" (linted, parameterized, pinned per Phase 33) but is not itself +deployed. The Foundry Next Gen adapter in this repo is exercised only through local runs and +CI's Docker health-check smoke test (`ci.yml`'s `docker` job) — never a live Azure deploy. + +## Reference-product contract + +Deploys as a Linux container image on port `8080` (internal ingress by default), exposing +`/health/live` and `/health/ready`. Workload configuration is non-secret and injected at +runtime; Application Insights connection strings are injected securely from the platform's +observability module outputs. + + diff --git a/docs/wiki/Decisions.md b/docs/wiki/Decisions.md new file mode 100644 index 0000000..c043a22 --- /dev/null +++ b/docs/wiki/Decisions.md @@ -0,0 +1,19 @@ +# Decisions + +This repo's `.planning/` tree holds `PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md`, and +`STATE.md` but no phase SUMMARY files as of this writing — the project is tracked at the +requirements/roadmap level rather than through executed phase plans in this repo's checkout. + +- [`.planning/PROJECT.md`](../../.planning/PROJECT.md) — goals and requirements +- [`.planning/ROADMAP.md`](../../.planning/ROADMAP.md) — roadmap +- [`.planning/REQUIREMENTS.md`](../../.planning/REQUIREMENTS.md) — requirements traceability +- [`docs/case-study-evidence.md`](../case-study-evidence.md) — immutable golden-path case-study + evidence, the closest artifact this repo has to a decision/evidence record + +## Architecture Decision Records (`docs/adr/`) + +[`docs/adr/`](../adr/README.md) is the formal ADR home for this repo. No sequentially-numbered +ADR files have been recorded yet as of this writing — the directory holds only the governance +README. + + diff --git a/docs/wiki/Home.md b/docs/wiki/Home.md new file mode 100644 index 0000000..645f1d0 --- /dev/null +++ b/docs/wiki/Home.md @@ -0,0 +1,38 @@ +# cas-reference-product Wiki + +`cas-reference-product` is the public v0.1 reference application for the Coding Autopilot +System and Microsoft Foundry Next Gen Agents. It runs a deterministic workflow locally, emits +canonical `cas-contracts` v0.1 lifecycle events, and includes a Foundry adapter that invokes a +Next Gen agent through the project Responses client. It is designed for the Container Apps and +managed-identity boundary supplied by `cas-platform`. + +## Deployment status: local-first, no live Azure deploy + +This project does not use Classic Assistants APIs and does not deploy Azure resources. See +[Architecture](Architecture.md) for the full NO-AZURE-deploy-lock statement. + +## Quickstart + +```powershell +./scripts/validate.ps1 +./scripts/run-local.ps1 +``` + +```powershell +Invoke-RestMethod ` + -Method Post ` + -Uri http://127.0.0.1:8080/api/v1/workflows ` + -ContentType application/json ` + -InFile examples/prompt-envelope.json +``` + +The local backend returns deterministic output and two canonical lifecycle events. It requires +no Azure account. + +## Where to go next + +- [Architecture](Architecture.md) — request flow, local vs. Foundry adapters, deploy-lock posture +- [Operations](Operations.md) — verified run/test/CI commands +- [Decisions](Decisions.md) — index of recorded architectural decisions + + diff --git a/docs/wiki/Operations.md b/docs/wiki/Operations.md new file mode 100644 index 0000000..744eee1 --- /dev/null +++ b/docs/wiki/Operations.md @@ -0,0 +1,61 @@ +# Operations + +## Local run + +```powershell +./scripts/validate.ps1 +./scripts/run-local.ps1 +``` + +Submit `examples/prompt-envelope.json` to `POST /api/v1/workflows`. Liveness is `/health/live`; +readiness is `/health/ready`. + +Hardened local container run: + +```powershell +docker run --rm --read-only --tmpfs /tmp --cap-drop ALL --security-opt no-new-privileges ` + -p 8080:8080 cas-reference-product:local +``` + +## CI gate (`.github/workflows/ci.yml`) + +The `validate` job (Python 3.12, `pip install -e ".[dev]"`) runs on every push/PR to `main`: + +```bash +python -m ruff check . +python -m mypy +python -m pytest tests/test_contract_registry.py -q --tb=short -o addopts="" +python -m pytest +python -m cas_reference_product.evidence +``` + +The contract-compatibility test is a consumer-side gate: it fails red if the pinned +`cas-contracts` version or the vendored v0.1 schema release drifts from what the Pydantic +models emit. + +The `docker` job builds a Linux/amd64 image, runs it locally with `ENVIRONMENT=local` and +`WORKFLOW_BACKEND=local`, health-checks `/health/live` and `/health/ready`, and — only on push +to `main` — pushes to GHCR. There is no coverage-percentage gate in this repo's CI as of this +writing; the gate is ruff/mypy/pytest/evidence pass-fail, not a coverage threshold. + +## Foundry mode + +Set `ENVIRONMENT` to `dev`/`test`/`prod`, `WORKFLOW_BACKEND=foundry`, and the non-secret +`FOUNDRY_PROJECT_ENDPOINT`/`FOUNDRY_AGENT_NAME`. The Azure-hosted workload uses its +system-assigned managed identity; no API keys or client secrets are configured. Readiness fails +until required Foundry identifiers are present; Foundry connectivity is exercised only by +workflow requests, not probes. + +## Platform handoff (validation only, no deploy) + +```powershell +az bicep build --file infra/main.bicep +az deployment group what-if --resource-group --template-file infra/main.bicep --parameters foundryProjectResourceId= +``` + +Deployment is intentionally not performed by repository validation — consistent with the +workspace NO-AZURE-deploy lock. Build a Linux AMD64 image and pass its immutable image reference +to the `containerImage` parameter of `cas-platform`; review +`deployment/cas-platform.interface.yaml` before platform changes. + +