microdao-daarion/docs/tasks/TASK_PHASE_GOVERNANCE_ENGINE.md

# 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
- [x] Agent Governance Views in AgentCabinet ✅
- [x] Report Button component ✅
- [x] GovernancePage with tabs ✅
- [x] Route `/governance` ✅
- [ ] District Governance Panel (TODO: окрема фаза)
- [ ] MicroDAO Governance Panel (TODO: окрема фаза)

### Tests
- [ ] Permission Engine unit tests
- [ ] Governance API integration tests
- [ ] Revocation flow tests
- [ ] Incidents escalation tests