feat(governance): Governance Engine MVP implementation

- Backend: - Migration 032: agent_gov_level, status, incidents, permissions tables - Domain types for governance layer - Permission Engine with all governance checks - Governance Service (promote/demote/roles) - Revocation Service (revoke/suspend/reinstate) - Audit Service (events filtering and stats) - Incidents Service (create/assign/escalate/resolve) - REST API routes for governance, audit, incidents - Frontend: - TypeScript types for governance - API clients for governance, audit, incidents - GovernanceLevelBadge component - CityGovernancePanel component - AuditDashboard component - IncidentsList component with detail modal Based on: Agent_Governance_Protocol_v1.md
2025-11-29 16:02:06 -08:00
parent 2627205663
commit e233d32ae7
20 changed files with 5837 additions and 0 deletions
--- a/docs/tasks/TASK_PHASE_GOVERNANCE_ENGINE.md
+++ b/docs/tasks/TASK_PHASE_GOVERNANCE_ENGINE.md
@@ -0,0 +1,405 @@
+# TASK_PHASE_GOVERNANCE_ENGINE.md
+
+## DAARION.city — Governance Engine, Revocation, Audit & Escalation (MVP)
+
+**Ціль:**  
+Реалізувати повноцінний Governance Engine згідно з:
+
+- `Agent_Governance_Protocol_v1.md`
+- `DAIS_Layer_Architecture_v1.md`
+- `Agents_Interface_Architecture_v1.md`
+- `Nodes_Interface_Architecture_v1.md`
+- `District_Interface_Architecture_v1.md`
+- `MicroDAO_Interface_Architecture_v1.md`
+- `Rooms_Layer_Architecture_v1.md`
+
+та підключити його до існуючих:
+
+- DAIS API (`/api/v1/dais/*`)
+- Assignments Layer (`/api/v1/assignments/*`)
+- Event Outbox (`event_outbox`)
+
+---
+
+## 1. Загальний опис задачі
+
+Побудувати **Governance Engine**, який:
+
+1. Інтерпретує ролі та рівні агентів (guest → city governance).
+2. Застосовує permissions до всіх ключових дій (create microdao, create node, create room, promote/revoke agent).
+3. Надає API для:
+   - призначення ролей,
+   - промоції,
+   - ревокації,
+   - перевірки доступу.
+4. Привʼязує всі governance-події до `event_outbox` для аудиту.
+5. Створює базовий Governance UI:
+   - City Governance Panel,
+   - District Governance Panel,
+   - MicroDAO Governance Panel.
+6. Додає просту систему ескалації інцидентів (tickets + escalation flow).
+7. Додає Audit Dashboard (читання `event_outbox` + фільтри).
+
+---
+
+## 2. BACKEND — Governance Engine
+
+### 2.1. Модель ролей і рівнів
+
+Орієнтуватися на `Agent_Governance_Protocol_v1.md`.
+
+Реалізувати enum/константи:
+
+- `AGENT_LEVEL_GUEST = 0`
+- `AGENT_LEVEL_PERSONAL = 1`
+- `AGENT_LEVEL_MEMBER = 2`
+- `AGENT_LEVEL_WORKER = 3`
+- `AGENT_LEVEL_CORE_TEAM = 4`
+- `AGENT_LEVEL_ORCHESTRATOR = 5`
+- `AGENT_LEVEL_DISTRICT_LEAD = 6`
+- `AGENT_LEVEL_CITY_GOV = 7`
+
+Зберігати рівень:
+
+- або в таблиці `agents.agent_role_level`,
+- або в окремій таблиці ролей (якщо вже є — узгодити).
+
+### 2.2. Permission Engine
+
+Створити модуль, умовно:
+
+- `governance/permissions.py` (або відповідний файл у вашому стеку)
+
+Функції:
+
+- `can_create_microdao(agent, context)`
+- `can_create_district(agent, context)`
+- `can_register_node(agent, context)`
+- `can_create_room(agent, context)`
+- `can_create_front_portal(agent, context)`
+- `can_promote_agent(actor, target, scope)`
+- `can_revoke_agent(actor, target, scope)`
+- `can_moderate_room(actor, room)`
+- `can_moderate_city_room(actor, room)`
+
+Усередині — логіка з `Agent_Governance_Protocol_v1.md`:
+
+- тільки Orchestrator може створювати MicroDAO;
+- District Lead / City Governance — створюють District;
+- Node Manager / Orchestrator / Core-team DevOps — реєструють ноди;
+- Core-team / Orchestrator — створюють DAO-wide rooms;
+- DARIO / DARIA / DAARWIZZ — міські кімнати;
+- City Governance — глобальна ескалація та revocation.
+
+### 2.3. Governance API
+
+Створити ендпоїнти (REST або GraphQL — згідно існуючого стилю):
+
+- `POST /api/v1/governance/agent/promote`
+  - body: `{ actor_id, target_id, new_level, scope }`
+  - перевірити `can_promote_agent`
+  - оновити роль/рівень
+  - записати подію в `event_outbox`
+
+- `POST /api/v1/governance/agent/revoke`
+  - body: `{ actor_id, target_id, reason, scope }`
+  - перевірити `can_revoke_agent`
+  - позначити агента як revoked / заблокувати ключі
+  - записати подію `agent.revoked` в `event_outbox`
+
+- `POST /api/v1/governance/agent/assign`
+  - body: `{ actor_id, target_id, scope_type, scope_id, role }`
+  - перевірити, чи actor має право на assign у цьому scope
+  - створити/оновити запис у Assignments Layer
+  - подія `agent.assigned`
+
+Додатково (якщо ще немає):
+
+- `GET /api/v1/governance/agent/:id/roles`
+- `GET /api/v1/governance/agent/:id/permissions`
+
+### 2.4. Інтеграція з Assignments Layer
+
+При промоції / assign:
+
+- створювати/оновлювати записи в `assignments` (таблиця, яка вже є в схемі).
+- використовувати `scope`:
+  - `city`
+  - `district:{id}`
+  - `microdao:{id}`
+  - `node:{id}`
+
+Переконатися, що Assignments однозначно відповідають ролям з Governance Protocol.
+
+---
+
+## 3. BACKEND — Revocation Engine
+
+### 3.1. DAIS Key Revocation
+
+На основі `DAIS_Layer_Architecture_v1.md`:
+
+- Додати метод для revocation ключів:
+  - позначити записи в `dais_keys` як `revoked=true`
+  - викидати помилки при спробі використання revoked-ключа.
+
+Створити API:
+
+- `POST /api/v1/dais/keys/revoke`
+  - body: `{ actor_id, dais_id, reason }`
+  - тільки City Governance / District Lead / Orchestrator (залежно від scope).
+
+### 3.2. Agent State
+
+Додати атрибут (якщо його ще нема) у `agents`:
+
+- `status` = `active | suspended | revoked`
+
+При revocation:
+
+- `status = revoked`
+- заблокувати виконання критичних дій цим агентом (через Permission Engine).
+
+---
+
+## 4. BACKEND — Audit & Event Outbox
+
+### 4.1. Події, які обовʼязково логувати
+
+Через `event_outbox`:
+
+- `agent.promoted`
+- `agent.revoked`
+- `agent.assigned`
+- `microdao.created`
+- `district.created`
+- `node.registered`
+- `room.created`
+- `room.published_to_city`
+- `incident.escalated`
+
+Створити helper:
+
+- `governance/log_event.py` або подібний модуль:
+  - `log_governance_event(type, actor_id, target_id, payload)`
+
+### 4.2. Audit API
+
+- `GET /api/v1/audit/events`
+  - фільтри: `type`, `actor_id`, `target_id`, `scope`, `created_at_from/to`
+- `GET /api/v1/audit/events/:id`
+
+---
+
+## 5. BACKEND — Escalation System (MVP)
+
+### 5.1. Таблиця `incidents`
+
+Створити таблицю:
+
+- `id`
+- `created_by_dais_id`
+- `target_scope_type` (`city|district|microdao|room|node|agent`)
+- `target_scope_id`
+- `status` (`open|in_progress|resolved|closed`)
+- `priority` (`low|medium|high|critical`)
+- `assigned_to_dais_id` (опціонально)
+- `escalation_level` (`microdao|district|city`)
+- `title`
+- `description`
+- `created_at`
+- `updated_at`
+
+### 5.2. API
+
+- `POST /api/v1/incidents/create`
+- `POST /api/v1/incidents/:id/assign`
+- `POST /api/v1/incidents/:id/escalate`
+- `POST /api/v1/incidents/:id/resolve`
+- `GET  /api/v1/incidents`
+- `GET  /api/v1/incidents/:id`
+
+Логувати у `event_outbox` події:
+
+- `incident.created`
+- `incident.assigned`
+- `incident.escalated`
+- `incident.resolved`
+
+Ескалація:
+
+- MicroDAO core-team → District Lead → City Governance (DAARWIZZ/DARIA).
+
+---
+
+## 6. FRONTEND — Governance UI
+
+### 6.1. City Governance Panel
+
+Сторінка (наприклад):
+
+- `/governance/city`
+
+Показує:
+
+- список city-agentів (DARIO, DARIA, DAARWIZZ, інші)
+- список Districts
+- список відкритих інцидентів з escalation_level=`city`
+- панель дій:
+  - promote/revoke agent (global / city scope)
+  - approve new district
+  - view audit events (фільтр по city)
+
+### 6.2. District Governance Panel
+
+Сторінка:
+
+- `/governance/district/[id]`
+
+Показує:
+
+- District Lead Agent
+- core-team district-рівня
+- підлеглі MicroDAO
+- інциденти з escalation_level=`district`
+- панель:
+  - призначення/зняття ролей в межах district
+  - view audit за district scope
+
+### 6.3. MicroDAO Governance Panel
+
+Сторінка:
+
+- `/governance/microdao/[id]` або вкладка в `/microdao/[id]`
+
+Показує:
+
+- Orchestrator
+- Core-team
+- Workers / Members
+- відкриті інциденти для цього DAO
+- панель:
+  - promote/demote agents у межах DAO
+  - revoke (локально або з ескалацією)
+  - audit DAO-подій
+
+---
+
+## 7. FRONTEND — Agent Governance Views
+
+У `AgentCabinet`:
+
+- блок "Ролі та повноваження":
+  - рівень агента (guest/personal/member/…)
+  - ролі у MicroDAO
+  - ролі у District
+  - участь на City рівні
+- блок "Дії" (видимий, якщо actor має права):
+  - promote
+  - revoke
+  - assign
+
+---
+
+## 8. FRONTEND — Audit Dashboard
+
+Сторінка:
+
+- `/audit`
+
+Функціонал:
+
+- список подій з `event_outbox`
+- фільтри: тип, actor, target, scope, період
+- детальний перегляд події
+- базова візуалізація (наприклад, кількість governance-подій за період)
+
+---
+
+## 9. FRONTEND — Incidents / Escalation UI
+
+Сторінки:
+
+- `/incidents`
+- `/incidents/[id]`
+
+Можливості:
+
+- створити інцидент із будь-якого контексту (room, microdao, district, node, agent):
+  - кнопка "Поскаржитись / Report"
+- перегляд:
+  - статус,
+  - масштаби,
+  - виконавець,
+  - історія змін,
+- дії (для тих, хто має права):
+  - assign to agent,
+  - escalate,
+  - resolve.
+
+---
+
+## 10. Тести та перевірка
+
+Cursor повинен:
+
+- додати unit-тести для Permission Engine,
+- додати інтеграційні тести для:
+  - promote,
+  - revoke,
+  - assign,
+  - incident escalation,
+- протестувати audit-лог (event_outbox) для ключових governance-дій.
+
+---
+
+## 11. Очікуваний результат TASK-фази
+
+Після завершення цієї фази:
+
+1. **Усі ключові дії в системі підконтрольні Governance Engine.**
+2. **Агенти не можуть перевищувати свої повноваження.**
+3. **Є чіткі API для промоції, ревокації, призначення ролей.**
+4. **Всі governance-події логуються в event_outbox.**
+5. **Є UI для City/District/MicroDAO-governance.**
+6. **Є Incidents/Escalation система для проблем і конфліктів.**
+7. **Є Audit Dashboard для аналізу історії рішень.**
+
+Це створює **надійний керований фундамент** для подальшого розвитку DAARION.city.
+
+---
+
+## 12. Checklist
+
+### Backend ✅
+- [x] Migration: `agents.agent_role_level`, `agents.status` fields
+- [x] Migration: `incidents` table
+- [x] Domain types: `governance/types.ts`
+- [x] Permission Engine: `governance/permissions.ts`
+- [x] Governance Service: `governance/governance.service.ts`
+- [x] Revocation Service: `governance/revocation.service.ts`
+- [x] Audit Service: `governance/audit.service.ts`
+- [x] Incidents Service: `governance/incidents.service.ts`
+- [x] Governance Routes: `governance.routes.ts`
+- [x] Audit Routes: `audit.routes.ts`
+- [x] Incidents Routes: `incidents.routes.ts`
+- [x] Event logging helper
+
+### Frontend ✅
+- [x] API clients: `governance.ts`, `audit.ts`, `incidents.ts`
+- [x] Types: `governance.ts`
+- [x] City Governance Panel
+- [x] Governance Level Badge component
+- [x] Audit Dashboard
+- [x] Incidents List & Detail
+- [ ] District Governance Panel (TODO: окрема фаза)
+- [ ] MicroDAO Governance Panel (TODO: окрема фаза)
+- [ ] Agent Governance Views in AgentCabinet (TODO: інтеграція)
+- [ ] Report Button component (TODO: інтеграція)
+
+### Tests
+- [ ] Permission Engine unit tests
+- [ ] Governance API integration tests
+- [ ] Revocation flow tests
+- [ ] Incidents escalation tests
+