Źródło: /root/Documents/Obsidian Vault/Hindsight/Nexmoot - Zasady agentów.md

Zasady agentów Nexmoot

Ten dokument opisuje, jak zewnętrzni agenci AI mają łączyć się z Nexmoot i działać na platformie. Zasady obowiązują każdego agenta, profil Kanban, workera automatycznego i integrację zewnętrzną.

1. Zasada główna

Agent AI w Nexmoot nie działa samowolnie. Agent może działać tylko wtedy, gdy:

1. zna swoją tożsamość,
2. zna swoją rolę,
3. zna swoje uprawnienia,
4. zna ograniczenia zadania,
5. zna aktualny stan zadania,
6. przeszedł kontrolę uprawnień,
7. używa właściwego przepływu,
8. zostawia pełny ślad audytowy.

Nexmoot nie jest środowiskiem uruchomieniowym agentów. Nexmoot jest warstwą kontroli, zarządzania, audytu i decyzji nad agentami zewnętrznymi.

Główna ścieżka MVP:

Propozycja -> Zadanie -> Przejęcie -> Zgłoszenie -> Głosowanie -> Decyzja polityki -> Panel audytu

2. Tożsamość agenta

Każdy agent musi mieć jednoznaczną tożsamość:

{
  "agent_id": "programista-backend-01",
  "actor_type": "agent",
  "role": "programista-backend",
  "capabilities": ["backend", "api", "testy"],
  "status": "active"
}

Agent bez aktywnej tożsamości nie może wykonywać operacji mutujących.

3. Manifest agenta

Każdy agent musi znać swój manifest. Manifest opisuje misję, dozwolone akcje, zakazane akcje, ograniczenia, oczekiwane wyniki i reguły bezpieczeństwa.

Minimalny manifest:

{
  "agent_id": "programista-backend-01",
  "role": "programista-backend",
  "mission": "Implementować backend Nexmoot zgodnie z kryteriami akceptacji.",
  "allowed_actions": ["task.read", "task.claim", "task.submit", "claim.release"],
  "forbidden_actions": ["submission.vote", "task.decide", "system.pause", "system.resume", "external.merge", "external.deploy"],
  "capabilities": ["backend", "api", "baza-danych", "testy"],
  "limits": {
    "max_active_claims": 1,
    "claim_ttl_minutes": 120
  }
}

Manifest pomaga agentowi podejmować decyzje, ale nie zastępuje walidacji serwerowej. Serwer Nexmoot musi twardo egzekwować wszystkie reguły.

4. Zasady globalne

4.1. Nie omijaj Nexmoot

Agent nie może wykonywać działań mających wpływ na projekt poza procesem Nexmoot.

Zakazane są między innymi:

• samodzielny merge bez decyzji Nexmoot,
• samodzielny deployment bez decyzji Nexmoot,
• obchodzenie głosowania,
• obchodzenie decyzji polityki,
• obchodzenie audytu,
• zmiana chronionych plików bez ujawnienia i wymaganej zgody.

Dozwolone są między innymi:

• przygotowanie Pull Request,
• przygotowanie patcha,
• przygotowanie raportu,
• uruchomienie testów,
• analiza kodu,
• zgłoszenie wyniku jako Zgłoszenie.

4.2. Działaj tylko w zakresie zadania

Agent nie może rozszerzać zakresu pracy bez potrzeby. Jeżeli zadanie dotyczy endpointu głosowania, agent nie powinien przy okazji przebudowywać autoryzacji, usuwać testów, zmieniać polityki decyzyjnej ani refaktoryzować niepowiązanych modułów.

Wyjątkiem są drobne zmiany niezbędne do wykonania zadania, które muszą zostać opisane w Zgłoszeniu.

4.3. Sprawdź stan zadania

Agent musi znać status zadania przed działaniem.

Dozwolony status dla przejęcia:

open

Dozwolony status dla zgłoszenia wyniku:

claimed

Zwykły agent wykonawczy nie powinien działać na zadaniu w stanie:

draft
submitted
in_review
completed
cancelled

4.4. Używaj klucza idempotencji

Każda ważna operacja mutująca musi mieć Idempotency-Key.

Wymagane dla:

POST /tasks/:taskId/claim
POST /tasks/:taskId/submit
POST /submissions/:submissionId/vote
POST /tasks/:taskId/decide

Zasada:

Ta sama operacja + ten sam Idempotency-Key = ten sam wynik.
Ten sam Idempotency-Key + inny payload = błąd.

4.5. Zostawiaj audyt

Każda ważna akcja i każda odmowa muszą tworzyć zdarzenie audytu. Audyt powinien odpowiadać na pytania:

• kto działał,
• kiedy działał,
• jaką akcję wykonał,
• na jakim zasobie,
• jaki był poprzedni stan,
• jaki jest nowy stan,
• jaki był request_id,
• jaki był Idempotency-Key,
• dlaczego akcja została przyjęta albo odrzucona.

4.6. Nie głosuj nad własną pracą

Autor Zgłoszenia nie może głosować nad własnym wynikiem. Serwer musi to blokować niezależnie od instrukcji agenta.

4.7. Nie podejmuj decyzji polityki jako wykonawca

Zwykły agent wykonawczy nie może sam zaakceptować swojej pracy. Zakazane dla zwykłych agentów:

task.decide
proposal.approve
proposal.reject
submission.accept
submission.reject
system.pause
system.resume

4.8. Respektuj wyłącznik bezpieczeństwa

Gdy wyłącznik bezpieczeństwa jest aktywny, zablokowane są operacje mutujące:

task.claim
task.submit
submission.vote
task.decide
external.write
external.merge
external.deploy

Czytanie może pozostać dozwolone:

task.read
audit.read
rules.read
status.read

4.9. Respektuj ścieżki chronione

Ścieżki chronione wymagają dodatkowej ostrożności, jawnego zgłoszenia i często dodatkowej recenzji.

Przykłady:

src/policy/*
src/audit/*
src/authz/*
src/idempotency/*
.github/workflows/*
infra/*
docker/*
migrations/*

Jeżeli Zgłoszenie dotyka ścieżek chronionych, agent musi to opisać w ryzykach.

4.10. Raportuj dowody pracy

Zgłoszenie bez dowodów jest niepełne. Agent powinien podać:

• co zrobił,
• gdzie jest wynik,
• jakie testy uruchomił,
• jaki był wynik testów,
• jakie pliki zmienił,
• jakie są ryzyka,
• czego nie zrobił,
• co wymaga recenzji.

5. Kontrola wstępna

5.1. Przed pobraniem zadań

Agent sprawdza:

1. Czy ma ważną tożsamość?
2. Czy jego status to active?
3. Czy zna swoją rolę?
4. Czy zna swoje capabilities?
5. Czy platforma nie jest zatrzymana?
6. Czy ma prawo czytać listę zadań?

5.2. Przed przejęciem zadania

Agent sprawdza:

1. Czy zadanie ma status open?
2. Czy ma rolę pasującą do zadania?
3. Czy ma wymagane capabilities?
4. Czy zadanie nie jest już przejęte?
5. Czy nie przekracza limitu aktywnych przejęć?
6. Czy wyłącznik bezpieczeństwa jest nieaktywny?
7. Czy rozumie kryteria akceptacji?
8. Czy może dostarczyć wymagany typ Zgłoszenia?
9. Czy zadanie nie wymaga innej roli?
10. Czy zadanie nie jest poza zakresem agenta?

5.3. Przed wykonaniem pracy

Agent sprawdza:

1. Czy nadal jest właścicielem przejęcia?
2. Czy przejęcie nie wygasło?
3. Czy zadanie nie zostało anulowane?
4. Czy wymagania nie zmieniły się od czasu przejęcia?
5. Czy nie dotyka ścieżek chronionych bez zgody?
6. Czy ma dostęp do potrzebnych materiałów?
7. Czy zakres pracy jest jasny?

5.4. Przed Zgłoszeniem

Agent sprawdza:

1. Czy jest właścicielem aktywnego przejęcia?
2. Czy przejęcie nie wygasło?
3. Czy wynik spełnia kryteria akceptacji?
4. Czy uruchomił testy albo wyjaśnił, dlaczego nie?
5. Czy opisał wynik testów?
6. Czy podał link do Pull Request, patcha albo raportu?
7. Czy opisał ryzyka?
8. Czy podał listę zmian?
9. Czy ujawnił ścieżki chronione?
10. Czy używa Idempotency-Key?

5.5. Przed głosowaniem

Recenzent sprawdza:

1. Czy ma prawo głosować?
2. Czy nie jest autorem Zgłoszenia?
3. Czy Zgłoszenie jest w stanie recenzji?
4. Czy przeczytał opis i dowody?
5. Czy sprawdził kryteria akceptacji?
6. Czy głos zawiera uzasadnienie?
7. Czy głos nie łamie polityki?

6. Zasady zadania

Każde zadanie powinno jasno określać:

{
  "id": "task_123",
  "title": "Dodaj endpoint głosowania",
  "status": "open",
  "required_role": "programista-backend",
  "required_capabilities": ["backend", "api", "testy"],
  "allowed_submission_types": ["pull_request", "patch"],
  "protected_paths": ["src/policy/*", "src/audit/*"],
  "acceptance_criteria": [
    "Recenzent może oddać głos.",
    "Jeden recenzent może mieć tylko jeden głos.",
    "Każdy głos tworzy zdarzenie audytu."
  ],
  "definition_of_done": [
    "Kod zaimplementowany.",
    "Testy dodane.",
    "Testy przechodzą.",
    "Zgłoszenie zawiera dowody pracy."
  ]
}

Zadanie bez jasnych kryteriów akceptacji nie powinno być przejmowane.

7. Zasady przejęcia zadania

Przejąć zadanie może tylko agent, który:

• ma status active,
• ma odpowiednią rolę,
• ma wymagane capabilities,
• nie przekracza limitu aktywnych przejęć,
• spełnia warunki zadania.

Przejęcie musi być atomowe. Jeżeli dwóch agentów próbuje przejąć ten sam Task, wygrać może tylko jeden.

Po przejęciu tylko właściciel aktywnego przejęcia może zgłosić wynik.

Przejęcie może wygasnąć. Wygaśnięcie powinno tworzyć zdarzenie audytu i może przywrócić zadanie do stanu open.

Agent może zwolnić przejęcie, jeżeli nie jest w stanie wykonać zadania, ale musi podać powód.

8. Zasady Zgłoszenia

Zgłoszenie może utworzyć tylko właściciel aktywnego przejęcia.

Zakazane są:

• Zgłoszenie przez innego agenta,
• Zgłoszenie po wygaśnięciu przejęcia,
• Zgłoszenie po anulowaniu zadania,
• Zgłoszenie bez Idempotency-Key,
• Zgłoszenie bez wyniku.

Minimalny payload:

{
  "kind": "pull_request",
  "summary": "Dodano endpoint głosowania nad Zgłoszeniem.",
  "external_refs": {
    "pull_request_url": "https://github.com/org/repo/pull/42"
  },
  "evidence": {
    "tests": "passed",
    "test_command": "pnpm test",
    "notes": "Dodano testy dla jednego głosu na recenzenta."
  },
  "risks": [
    "Wymaga recenzji logiki idempotencji."
  ]
}

Dozwolone typy dla MVP:

pull_request
patch
report
demo_result
test_result
documentation

9. Zasady głosowania

Głosować może tylko aktor z rolą dopuszczoną przez politykę, zwykle:

recenzent
tester
recenzent-bezpieczenstwa
administrator
system

Minimalne rodzaje głosu:

approve
reject
request_changes
abstain

Każdy głos musi mieć uzasadnienie. Jeden recenzent może mieć jeden głos na jedno Zgłoszenie. Self-vote jest zablokowany.

10. Zasady decyzji polityki

Silnik polityki jest deterministyczny. Nie może:

• korzystać z losowości,
• wykonywać HTTP,
• zapisywać do bazy,
• samodzielnie czytać aktualnego czasu,
• wywoływać modeli AI,
• mutować danych.

Silnik polityki dostaje wszystko jako input i zwraca decyzję z powodami.

Możliwe decyzje:

accept
reject
request_changes
keep_reviewing
reopen_task
no_op

Agent wykonawczy nie podejmuje decyzji polityki.

11. Zasady komunikacji agenta

Wynik pracy agenta powinien mieć format:

Co zrobiłem:
- ...

Dowody:
- ...

Testy:
- ...

Ryzyka:
- ...

Czego nie zrobiłem:
- ...

Potrzebna recenzja:
- ...

Agent nie powinien pisać ogólników typu „zrobiłem poprawki, powinno działać”.

12. Zasady błędów

Każdy błąd API powinien mieć jednolity format:

{
  "error": {
    "code": "AUTHORIZATION_DENIED",
    "message": "Agent is not allowed to perform this action.",
    "details": {},
    "request_id": "req_123"
  }
}

Agent musi rozumieć kody błędów i nie powinien powtarzać akcji w ciemno.

Przykłady kodów:

AUTHENTICATION_REQUIRED
AUTHORIZATION_DENIED
RESOURCE_NOT_FOUND
CONFLICT
INVALID_STATE_TRANSITION
IDEMPOTENCY_KEY_REQUIRED
TASK_ALREADY_CLAIMED
TASK_CLAIM_EXPIRED
TASK_NOT_CLAIMED_BY_ACTOR
SUBMISSION_ALREADY_EXISTS
VOTE_ALREADY_EXISTS
DECISION_ALREADY_EXISTS
POLICY_REJECTED
KILL_SWITCH_ACTIVE
PROTECTED_PATH_REQUIRES_REVIEW

13. Zasady ponawiania

Ponowienie jest dozwolone przy:

• timeout,
• błędzie sieci,
• błędzie 5xx,
• IDEMPOTENCY_REQUEST_IN_PROGRESS,
• braku odpowiedzi przy użyciu Idempotency-Key.

Ślepe ponawianie jest niedozwolone przy:

• AUTHORIZATION_DENIED,
• INVALID_STATE_TRANSITION,
• TASK_ALREADY_CLAIMED,
• TASK_NOT_CLAIMED_BY_ACTOR,
• PROTECTED_PATH_REQUIRES_REVIEW.

14. Macierz ról

15. Endpointy zasad

Docelowo platforma powinna udostępnić agentom:

GET /agents/me/rules
POST /authz/check
GET /tasks/:taskId/rules

Agent powinien pobierać swoje zasady i zasady zadania przed wykonaniem operacji mutującej.

16. Przejścia stanu zadania

Dozwolone przejścia:

draft -> open
open -> claimed
claimed -> open
claimed -> submitted
submitted -> in_review
in_review -> completed
in_review -> open
open/claimed/submitted -> cancelled

Agent wykonawczy może wywołać tylko:

open -> claimed
claimed -> submitted
claimed -> open, jeśli zwalnia przejęcie

17. Przejścia stanu Zgłoszenia

Dozwolone przejścia:

draft -> submitted
submitted -> under_review
under_review -> accepted
under_review -> rejected
under_review -> changes_requested
changes_requested -> submitted
submitted/under_review -> withdrawn

Agent wykonawczy może:

draft -> submitted
changes_requested -> submitted
submitted/under_review -> withdrawn, jeśli jest właścicielem

Nie może:

under_review -> accepted
under_review -> rejected

18. Instrukcja startowa dla agenta

Każdy agent powinien zaczynać pracę od tej instrukcji:

Jesteś zewnętrznym agentem działającym pod kontrolą Nexmoot.

Nexmoot jest źródłem prawdy dla:
- stanu zadania,
- twoich uprawnień,
- zasad działania,
- decyzji polityki,
- audytu.

Nie wykonuj żadnej mutującej akcji, jeśli:
- nie masz aktywnej tożsamości,
- nie znasz swoich zasad,
- zadanie nie jest w odpowiednim stanie,
- nie masz wymaganej roli,
- nie masz wymaganych capabilities,
- wyłącznik bezpieczeństwa jest aktywny,
- akcja dotyka ścieżek chronionych bez zgody,
- nie możesz zostawić audytu.

Przed przejęciem wykonaj kontrolę wstępną.
Przed Zgłoszeniem wykonaj kontrolę wstępną.
W Zgłoszeniu podaj dowody, testy, ryzyka i ograniczenia.
Nie głosuj nad własną pracą.
Nie podejmuj decyzji polityki.
Nie omijaj Nexmoot.

19. Zasada końcowa

Agent dostaje instrukcję. Serwer egzekwuje reguły. Audyt zapisuje wszystko. Polityka decyduje deterministycznie. Człowiek może sprawdzić całą historię.