docs(platform): add policy configs, runbooks, ops scripts and platform documentation

Config policies (16 files): alert_routing, architecture_pressure, backlog, cost_weights, data_governance, incident_escalation, incident_intelligence, network_allowlist, nodes_registry, observability_sources, rbac_tools_matrix, release_gate, risk_attribution, risk_policy, slo_policy, tool_limits, tools_rollout Ops (22 files): Caddyfile, calendar compose, grafana voice dashboard, deployments/incidents logs, runbooks for alerts/audit/backlog/incidents/sofiia/voice, cron jobs, scripts (alert_triage, audit_cleanup, migrate_*, governance, schedule), task_registry, voice alerts/ha/latency/policy Docs (30+ files): HUMANIZED_STEPAN v2.7-v3 changelogs and runbooks, NODA1/NODA2 status and setup, audit index and traces, backlog, incident, supervisor, tools, voice, opencode, release, risk, aistalk, spacebot Made-with: Cursor
2026-03-03 07:14:53 -08:00
parent 129e4ea1fc
commit 67225a39fa
102 changed files with 20060 additions and 0 deletions
--- a/docs/opencode/sofiia_setup.md
+++ b/docs/opencode/sofiia_setup.md
@@ -0,0 +1,139 @@
+# OpenCode ↔ Sofiia Integration
+
+Sofiia (CTO agent) is exposed to OpenCode via the **DAARION router** tool execution endpoint. No extra adapter service is required for basic tool calls.
+
+---
+
+## 1. Environment variables
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `ROUTER_URL` | Base URL of the DAARION router | `http://localhost:8000` or `http://router:8000` |
+| `SUPERVISOR_API_KEY` | Optional. If set, router requires `Authorization: Bearer <key>` on `/v1/tools/execute` | (secret) |
+
+Set these in your OpenCode environment or in the config that invokes Sofiia.
+
+---
+
+## 2. Agent endpoint (for OpenCode “invoke agent”)
+
+- **Tool execution (primary):**  
+  `POST {ROUTER_URL}/v1/tools/execute`
+
+- **Chat / inference:**  
+  `POST {ROUTER_URL}/v1/agents/sofiia/infer`
+
+OpenCode can treat Sofiia as an agent whose “tools” are executed by POSTing to `/v1/tools/execute` with a JSON body (see below). There is no separate “invoke” URL; tool execution **is** the invocation.
+
+---
+
+## 3. Tool execution contract
+
+**Request:**
+
+```http
+POST /v1/tools/execute
+Content-Type: application/json
+Authorization: Bearer <SUPERVISOR_API_KEY>   # optional
+
+{
+  "tool": "risk_engine_tool",
+  "action": "service",
+  "agent_id": "sofiia",
+  "env": "prod",
+  "service": "gateway"
+}
+```
+
+**Response:**
+
+```json
+{
+  "status": "succeeded",
+  "data": { ... },
+  "error": null
+}
+```
+
+or on failure:
+
+```json
+{
+  "status": "failed",
+  "data": null,
+  "error": {
+    "code": "tool_error",
+    "message": "...",
+    "retryable": false
+  }
+}
+```
+
+All parameters beyond `tool`, `action`, and `agent_id` are passed as the tool’s arguments (e.g. `env`, `service`, `task_id`, `inputs`).
+
+---
+
+## 4. Hello-world: one tool call
+
+```bash
+export ROUTER_URL="http://localhost:8000"
+# Optional: export SUPERVISOR_API_KEY="your-key"
+
+curl -s -X POST "$ROUTER_URL/v1/tools/execute" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $SUPERVISOR_API_KEY" \
+  -d '{
+    "tool": "backlog_tool",
+    "action": "dashboard",
+    "agent_id": "sofiia",
+    "env": "prod"
+  }'
+```
+
+Expected: `"status": "succeeded"` and `"data"` with backlog summary.
+
+---
+
+## 5. How to verify (one command)
+
+From the repo root:
+
+```bash
+python3 ops/scripts/verify_sofiia_stack.py --router-url "$ROUTER_URL"
+```
+
+This checks:
+
+- Router `/healthz` (or `/health`)
+- Dry-run tool calls: `risk_engine_tool.service`, `architecture_pressure_tool.service`, `backlog_tool.dashboard`
+- Presence of governance cron entries in `ops/cron/jobs.cron`
+- Optional: supervisor health if `SUPERVISOR_URL` is set
+
+Exit code 0 = all checks PASS.
+
+---
+
+## 6. Typical tools for OpenCode-driven flows
+
+| Tool | Action | Typical use |
+|------|--------|-------------|
+| `risk_engine_tool` | `service`, `dashboard` | Risk score / dashboard |
+| `architecture_pressure_tool` | `service`, `dashboard`, `digest` | Pressure index, weekly digest |
+| `backlog_tool` | `dashboard`, `list`, `create`, `auto_generate_weekly` | Backlog ops |
+| `job_orchestrator_tool` | `start_task` | e.g. `task_id: "release_check"` for release gates |
+| `oncall_tool` | `incident_create`, `list` | Incidents |
+| `incident_intelligence_tool` | `correlate`, `recurrence`, `weekly_digest` | Intelligence |
+
+OpenCode can “Ask Sofiia to run release_check” by calling `/v1/tools/execute` with `tool: "job_orchestrator_tool"`, `action: "start_task"`, `task_id: "release_check"`, `inputs: { "gate_profile": "staging" }`.
+
+---
+
+## 7. Sofiia Control Console (optional)
+
+A minimal web UI for chat + ops + nodes is provided by **sofiia-console** (NODA2 primary):
+
+- Chat: proxy to `POST /v1/agents/sofiia/infer`
+- Ops: Risk/Pressure/Backlog/Release check via `POST /v1/tools/execute`
+- Nodes: dashboard from `config/nodes_registry.yml`
+
+See `services/sofiia-console/` and runbook for deployment. OpenCode integration does **not** depend on the console; the console is for human operators.