Coding-Autopilot-System · OgeonX-Ai · Jul 8, 2026 · Jul 8, 2026
diff --git 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).
+
+<!-- docs-verified: 57c21b03a48332728105b72a90e8e89deda409af 2026-07-08 -->
diff --git a/docs/wiki/Architecture.md 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
+```
+
+<!-- codex:generate-image prompt="A single reference workbench with two interchangeable adapter modules plugged into the same socket, one glowing green labeled Local (deterministic, offline), the other labeled Foundry with a dotted cable running to a distant locked cloud icon; isometric, enterprise blue/graphite palette" style="isometric, enterprise, clean" replaces="mermaid-above" -->
+
+## 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.
+
+<!-- docs-verified: 57c21b03a48332728105b72a90e8e89deda409af 2026-07-08 -->
diff --git a/docs/wiki/Decisions.md 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.
+
+<!-- docs-verified: 57c21b03a48332728105b72a90e8e89deda409af 2026-07-08 -->
diff --git a/docs/wiki/Home.md 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
+
+<!-- docs-verified: 57c21b03a48332728105b72a90e8e89deda409af 2026-07-08 -->
diff --git a/docs/wiki/Operations.md 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 <resource-group> --template-file infra/main.bicep --parameters foundryProjectResourceId=<resource-id>
+```
+
+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.
+
+<!-- docs-verified: 57c21b03a48332728105b72a90e8e89deda409af 2026-07-08 -->