# Sofiia CTO Agent — Audit Index (A)

> Generated: 2026-02-26 | Scope: Full repository scan | Author: Cursor Auditor

---

## 1. Canonical Files (Топ-10 "Sources of Truth")

| # | File | Тип | Статус | Короткий опис |
|---|------|-----|--------|---------------|
| 1 | `AGENTS.md` | Identity/Capabilities | ✅ Актуальний | Головний identity файл Sofiia. CTO-агент, 3 ноди, всі можливості, toolchain |
| 2 | `config/agent_registry.yml` | Config Registry | ✅ Актуальний | Single Source of Truth для конфігурації. Sofiia entry ~рядки 1276–1330 |
| 3 | `services/sofiia-console/app/main.py` | BFF Implementation | ✅ Актуальний | FastAPI BFF v0.3.0. Всі endpoint-и Control Console |
| 4 | `services/sofiia-console/static/index.html` | UI | ✅ Актуальний | 1600+ рядків SPA. Чат, Projects, Ops, Hub, Nodes, Memory |
| 5 | `docs/ADR_ARCHITECTURE_VNEXT.md` | Architecture ADR | ✅ Актуальний (2026-01-19) | Control Plane + Data Plane архітектура, Privacy Gate, NATS standards |
| 6 | `services/router/router-config.yml` | Router Config | ✅ Актуальний | LLM profiles, voice policies, agent routing |
| 7 | `config/rbac_tools_matrix.yml` | Security | ✅ Актуальний | `agent_cto` роль з 39 дозволами |
| 8 | `docs/OPENAPI_CONTRACTS.md` | API Contracts | ✅ Актуальний | Gateway→Router, Router→Memory контракти |
| 9 | `docs/architecture_inventory/` | Inventory (7 файлів) | ✅ Актуальний (2026-02-16) | Повний каталог сервісів, інструментів, NATS, безпека |
| 10 | `gateway-bot/sofiia_prompt.txt` | System Prompt | ✅ Актуальний | 138KB+ Telegram-промпт Sofiia як Chief AI Architect |

---

## 2. Повна Карта Файлів

### 2.1 Identity та промпти

| Файл | Опис | Розмір | Стан |
|------|------|--------|------|
| `AGENTS.md` | Sofiia identity: CTO-агент, NODA1/NODA2/NODA3, інструменти, стиль | ~400 рядків | ✅ Канонічний |
| `gateway-bot/sofiia_prompt.txt` | Telegram system prompt (великий, детальний) | ~138KB | ✅ Production |
| `services/sofiia-console/app/main.py` lines 138–177 | Console embedded system prompt (BFF) | ~1KB | ✅ Production |
| `docs/consolidation/_node1_runtime_docs/gateway-bot/sofiia_prompt.txt` | Копія промпту (NODA1 backup) | ~138KB | ⚠️ Backup copy |

### 2.2 Core Implementation — sofiia-console

| Файл | Опис | Рядків |
|------|------|--------|
| `services/sofiia-console/app/main.py` | BFF FastAPI: всі endpoints, voice, telemetry, degradation SM | ~1800 |
| `services/sofiia-console/app/docs_router.py` | Projects/Documents/Sessions/Dialog Map router | ~380 |
| `services/sofiia-console/app/db.py` | SQLite async CRUD: projects, documents, sessions, messages, dialog map | ~320 |
| `services/sofiia-console/app/auth.py` | API key authentication | ~50 |
| `services/sofiia-console/app/config.py` | Node registry, URLs, feature flags | ~100 |
| `services/sofiia-console/app/monitor.py` | Multi-node health polling | ~150 |
| `services/sofiia-console/app/nodes.py` | Nodes dashboard | ~80 |
| `services/sofiia-console/app/ops.py` | Ops actions dispatcher | ~200 |
| `services/sofiia-console/app/router_client.py` | Proxy до Router (infer, tools, health) | ~100 |
| `services/sofiia-console/app/voice_utils.py` | Voice sanitize, chunk split, think-block clean | ~150 |
| `services/sofiia-console/app/adapters/aistalk.py` | AISTALK adapter | ~80 |
| `services/sofiia-console/static/index.html` | SPA UI: chat, projects, ops, hub, nodes, memory | ~1600 |
| `services/sofiia-console/requirements.txt` | aiosqlite, pypdf, python-docx, fastapi, httpx | 10 рядків |
| `services/sofiia-console/Dockerfile` | Docker build | ~25 |

### 2.3 Sofiia Supervisor (LangGraph)

| Файл | Опис |
|------|------|
| `services/sofiia-supervisor/app/main.py` | FastAPI: `/v1/graphs/{name}/runs` API |
| `services/sofiia-supervisor/app/graphs/alert_triage_graph.py` | Alert triage LangGraph |
| `services/sofiia-supervisor/app/graphs/incident_triage_graph.py` | Incident triage LangGraph |
| `services/sofiia-supervisor/app/graphs/postmortem_draft_graph.py` | Postmortem LangGraph |
| `services/sofiia-supervisor/app/graphs/release_check_graph.py` | Release check LangGraph |
| `services/sofiia-supervisor/app/alert_routing.py` | Routing policy matcher |
| `services/sofiia-supervisor/app/gateway_client.py` | RBAC-enforced gateway client |
| `services/sofiia-supervisor/app/models.py` | Pydantic models |
| `services/sofiia-supervisor/app/state_backend.py` | Redis/in-memory state |
| `docker-compose.node2-sofiia-supervisor.yml` | Supervisor Docker Compose |
| `services/sofiia-supervisor/tests/` | 6 test files |

### 2.4 Router та Tools

| Файл | Опис |
|------|------|
| `services/router/main.py` | Main router: всі API endpoints, voice HA, capabilities |
| `services/router/tool_manager.py` | 20+ інструментів: CRUD, exec, governance |
| `services/router/agent_tools_config.py` | Per-agent tool allowlists |
| `services/router/router-config.yml` | LLM profiles, voice policies, agent routing |
| `services/router/fabric_metrics.py` | Prometheus metrics |
| `services/router/offload_client.py` | NATS offload client |
| `services/router/risk_engine.py` | Risk assessment engine |
| `services/router/backlog_generator.py` | Backlog generation |
| `services/router/incident_intelligence.py` | Incident correlation |
| `services/router/cost_analyzer.py` | Cost analysis tool |
| `services/router/data_governance.py` | Data governance |
| `services/router/dependency_scanner.py` | Dependency scanner |
| `services/router/drift_analyzer.py` | Infrastructure drift |
| `services/router/architecture_pressure.py` | Architecture pressure analysis |

### 2.5 Memory Service

| Файл | Опис |
|------|------|
| `services/memory-service/app/main.py` | FastAPI: threads, events, memories, facts, agent memory |
| `services/memory-service/app/vector_store.py` | Qdrant integration |
| `services/memory-service/app/voice_endpoints.py` | STT/TTS endpoints з Prometheus metrics |
| `services/memory-service/app/integration_endpoints.py` | Integration webhooks |
| `services/memory-service/app/integrations.py` | External integrations |

### 2.6 Configuration

| Файл | Опис |
|------|------|
| `config/agent_registry.yml` | Всі 13+ агентів + sofiia entry |
| `config/rbac_tools_matrix.yml` | RBAC ролі: `agent_cto` (39 permissions) |
| `config/slo_policy.yml` | SLO для voice fast/quality profiles |
| `config/risk_policy.yml` | Risk scoring policy |
| `config/release_gate_policy.yml` | Release gate rules |
| `config/incident_escalation_policy.yml` | Escalation policy |
| `config/alert_routing_policy.yml` | Alert routing |
| `config/observability_sources.yml` | Prometheus/Loki/Tempo sources |
| `config/tool_limits.yml` | Tool rate limits |
| `config/tools_rollout.yml` | Tools rollout configuration |
| `config/cost_weights.yml` | Cost scoring weights |
| `config/network_allowlist.yml` | Network access allowlist |
| `config/nodes_registry.yml` | NODA1/NODA2 node registry |
| `config/data_governance_policy.yml` | Data governance policy |
| `config/backlog_policy.yml` | Backlog generation policy |
| `services/router/router-config.yml` | Voice profiles, agent routing |

### 2.7 Docker Compose (NODA2 Sofiia Stack)

| Файл | Опис |
|------|------|
| `docker-compose.node2-sofiia.yml` | Main: sofiia-console + router + node-worker + memory + qdrant |
| `docker-compose.node2-sofiia-supervisor.yml` | Sofiia Supervisor + Redis |
| `docker-compose.memory-node2.yml` | Memory stack: Postgres + Qdrant + Neo4j + Memory Service |
| `docker-compose.node2.yml` | Full NODA2 stack |

### 2.8 Документація (docs/)

| Файл/Dir | Опис | Стан |
|----------|------|------|
| `docs/ADR_ARCHITECTURE_VNEXT.md` | Основний ADR: vNext архітектура | ✅ |
| `docs/OPENAPI_CONTRACTS.md` | API контракти Gateway↔Router↔Memory | ✅ |
| `docs/ARCHITECTURE_DIAGRAM.md` | Діаграма архітектури | ✅ |
| `docs/architecture_inventory/` | 7 файлів: exec summary, service catalog, tool catalog, dataflows, security, observability, open questions | ✅ 2026-02-16 |
| `docs/fabric_contract.md` | Fabric multi-node contract, Voice HA | ✅ |
| `docs/sofiia_ui_vnext_audit.md` | vNext UI audit | ✅ |
| `docs/supervisor/langgraph_supervisor.md` | Supervisor архітектура | ✅ |
| `docs/supervisor/postmortem_draft_graph.md` | Postmortem граф | ✅ |
| `docs/runbook/sofiia-control-plane.md` | Operations runbook | ✅ |
| `docs/NODA1-NODA2-STATUS.md` | Статус нод | ✅ |
| `docs/MULTINODE_ARCHITECTURE.md` | Multi-node архітектура | ✅ |
| `docs/NATS_SUBJECTS.md` | NATS subject map | ✅ |
| `docs/voice_phase2_cutover.md` | Voice Phase 2 cutover plan | ✅ |
| `docs/voice_streaming_phase2.md` | Voice Phase 2 spec | ✅ |
| `docs/PRIVACY_GATE.md` | Privacy gate policy | ✅ |
| `docs/DATA_RETENTION_POLICY.md` | Data retention | ✅ |
| `docs/MEMORY_API_POLICY.md` | Memory API policy | ✅ |
| `docs/AGENT_RUNTIME_POLICY.md` | Agent runtime policy | ✅ |
| `docs/SECURITY_HARDENING_SUMMARY.md` | Security hardening | ✅ |
| `docs/backlog/backlog.md` | Поточний беклог | ✅ |
| `docs/incident/` | Incident tracking docs | ✅ |
| `docs/risk/risk_index.md` | Risk index | ✅ |

### 2.9 Тести

| Файл | Що тестує |
|------|-----------|
| `tests/test_voice_ha.py` | Voice HA: 35 tests |
| `tests/test_voice_policy.py` | Voice routing policy: 23 tests |
| `tests/test_voice_stream.py` | Voice Phase 2 streaming: 22 tests |
| `tests/test_sofiia_docs.py` | Projects/Documents/Sessions/Dialog Map: 28 tests |
| `tests/test_tool_governance.py` | Tool RBAC (agent_cto role) |
| `tests/test_risk_attribution.py` | Risk engine |
| `tests/test_drift_analyzer.py` | Drift analyzer |
| `tests/test_cost_analyzer.py` | Cost analyzer |
| `tests/test_incident_escalation.py` | Escalation |
| `tests/test_backlog_*.py` | Backlog generation/store |
| `services/sofiia-supervisor/tests/` | 6 supervisor graph tests |

### 2.10 Ops Scripts

| Файл | Опис |
|------|------|
| `ops/fabric_preflight.sh` | Preflight checks: models, canary, voice |
| `ops/voice_ha_smoke.sh` | Voice HA acceptance smoke test |
| `ops/voice_latency_audit.sh` | Multi-scenario latency audit |
| `ops/voice_policy_update.py` | Auto-update voice policy від audit results |
| `ops/scripts/voice_canary.py` | Voice health canary (preflight + runtime) |
| `ops/runbook-voice-incidents.md` | Voice incident runbook |
| `ops/runbook-sofiia-docs.md` | Projects/Docs runbook |
| `ops/grafana_voice_dashboard.json` | Grafana dashboard |
| `ops/voice_alerts.yml` | Prometheus alerting rules |

---

## 3. Відсутні файли (NOT FOUND — очікувались)

| Очікуваний файл | Чому очікувався | Статус |
|-----------------|-----------------|--------|
| `services/projects-service/` | ADR_ARCHITECTURE_VNEXT згадує окремий projects-service | ❌ НЕ ЗНАЙДЕНО |
| `services/docs-service/` | ADR згадує окремий docs-service з версіями | ❌ НЕ ЗНАЙДЕНО |
| `services/dialogmap-service/` | vNext design, описаний у chat | ❌ НЕ ЗНАЙДЕНО |
| `services/ingest-service/` | ADR 2.2 Ingest Service | ❌ НЕ ЗНАЙДЕНО (тільки stub reference) |
| `openapi.yml` / `swagger.yml` | Формальна OpenAPI специфікація | ❌ НЕ ЗНАЙДЕНО |
| `migrations/` (Postgres DDL для sofiia) | Versioned DB migrations | ⚠️ Є `migrations/046, 049, 052` для memory-service, але не для sofiia-console |
| `docs/audit/` (5 аудит-файлів) | Запит цього сеансу | ✅ Створюються зараз |
| `docs_versions` table | vNext DDL план | ❌ НЕ РЕАЛІЗОВАНО |
| `dialog_nodes` / `dialog_edges` tables (Postgres) | vNext Dialog Map | ⚠️ SQLite-тільки, tree-based |
| `entity_links` / `repo_changesets` / `ops_runs` | CTO DDL заготовки | ❌ НЕ ЗНАЙДЕНО |

---

## Next Actions for UI Team (1–2 days)

1. **Ознайомитись з `docs/architecture_inventory/` (7 файлів)** — там повний каталог поточного стеку
2. **Перевірити `services/sofiia-console/app/docs_router.py`** — Projects/Documents/Sessions API вже є, потрібно тільки вмикати USE_EMBEDDINGS/USE_FABRIC_OCR
3. **`config/agent_registry.yml` Sofiia entry** — перевірити `telegram_mode: whitelist` і `allowed_users: []`
4. **Впевнитись що `docker-compose.node2-sofiia.yml`** має `sofiia-data` volume з правильним path
5. **Протестувати UI** через `http://localhost:8002/` — відкрити вкладку "📁 Проєкти" і перевірити sidebar
6. **Перевірити Dialog Map** через `GET /api/sessions/{sid}/map` — tree view реалізований
7. **НОВА ПОТРЕБА**: визначити де буде Dialog Map на Postgres (`dialog_nodes/edges`) — поки SQLite tree-only
8. **Пріоритет для UI**: mock endpoints для `repo_changesets` і `ops_runs` (CTO panel) поки не реалізовано
9. **Додати `docs_versions` endpoint** в `docs_router.py` (колонка `extracted_text` є, потрібна таблиця версій)
10. **Перевірити NATS subjects** в `docs/NATS_SUBJECTS.md` і зіставити з поточними з `docs/ADR_ARCHITECTURE_VNEXT.md §5`