Metadata-Version: 2.4
Name: ifuri-todo-agent
Version: 0.8.1
Summary: Central task registry and deterministic three-agent orchestrator for doctor-agent, repair-agent and validator-agent.
Author: todo-agent maintainers
License: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: jsonschema<5,>=4.26.0
Requires-Dist: PyYAML<7,>=6.0.3
Provides-Extra: dev
Requires-Dist: pytest<10,>=9.1.1; extra == "dev"
Requires-Dist: pytest-cov<7,>=6; extra == "dev"
Requires-Dist: ruff<1,>=0.15.21; extra == "dev"
Provides-Extra: planfile
Requires-Dist: planfile>=0.1.112; extra == "planfile"
Provides-Extra: urirun
Requires-Dist: urirun>=0.4.190; extra == "urirun"
Dynamic: license-file

# todo-agent

`todo-agent` jest centralnym rejestrem pakietów zadań i deterministyczną warstwą orkiestracji dla trzech istniejących wykonawców:

- **doctor-agent** — diagnoza i dowody, bez naprawiania systemu,
- **repair-agent** — plan lub kontrolowana zmiana przez pull request,
- **validator-agent** — niezależna walidacja diagnozy, planu i rezultatów.

Repozytorium nie zastępuje tych agentów. Stanowi **control plane**: 
przechowuje kontrakty zadań, wybiera zadania gotowe do wykonania, uruchamia etapy w stałej kolejności i waliduje hand-offy JSON. Agenci pozostają osobnymi **execution planes** z własną logiką domenową.

## Najważniejsze właściwości

- jedna, walidowana definicja `task.yaml`,
- katalog per zadanie i per agent: `TODO/<id>/<agent>/...`,
- sekwencja `doctor → repair → validator`,
- izolowany katalog każdego uruchomienia,
- ścisłe kontrakty JSON Schema dla wyników agentów,
- planowanie harmonogramu z timezone zapisanym w zadaniu,
- domyślny tryb bez zapisu; mutacje wyłącznie jako pull request po zatwierdzeniu środowiska,
- uwierzytelnianie między repozytoriami krótkotrwałym tokenem GitHub App,
- deterministyczne generowanie scaffoldów oraz opcjonalne wejście NL przez GitHub Models,
- brak obowiązkowej zależności od płatnego GitHub Copilot/Codex,
- opcjonalny rejestr zadań na `planfile` (`todo-agent tickets`),
- opcjonalne monitorowanie procesów na `urirun` (`todo-agent process`).

## Struktura repozytorium

```text
.
├── TODO/
│   └── 0001_org-repo-audit/
│       ├── task.yaml
│       ├── README.md
│       ├── doctor-agent/{README.md,run.py,input/,output/,logs/}
│       ├── repair-agent/{README.md,run.py,input/,output/,logs/}
│       └── validator-agent/{README.md,run.py,input/,output/,logs/}
├── schemas/                 # kontrakty zadań, agentów i repo docelowych
├── src/todo_agent/          # discovery, walidacja, runner, scaffold i bootstrap
├── scripts/                 # cienkie entrypointy do CI
├── templates/               # czytelne szablony dla ludzi
├── docs/                    # architektura, bezpieczeństwo i plan wdrożenia
└── .github/workflows/       # CI, orkiestrator, ręczne uruchomienie i generator NL
```

## Pakiet zadania

`task.yaml` jest źródłem prawdy dla automatu. `README.md` zawiera kontekst dla człowieka. Każdy agent ma własny entrypoint i katalogi runtime.

```text
TODO/0042_customer-mail-triage/
├── task.yaml
├── README.md
├── doctor-agent/
│   ├── README.md
│   ├── run.py
│   ├── input/
│   ├── output/
│   └── logs/
├── repair-agent/
└── validator-agent/
```

Status `ready` oznacza, że kod zadania, kontrakty i kryteria akceptacji są gotowe do uruchomienia. Generator zawsze tworzy task ze statusem `todo`, aby wygenerowana treść nie została wykonana bez przeglądu.

## Rejestr zadań (planfile) i procesy (urirun)

todo-agent działa w oparciu o **listę zadań** i **monitorowanie procesów**, ale
oba filary są od siebie oddzielone i obie zależności są opcjonalne:

- **Lista zadań — `planfile`.** Kontraktem wykonania pozostaje
  `TODO/<id>/task.yaml`, natomiast rejestrem/backlogiem jest store `planfile`.
  Każde zadanie jest rzutowane na bilet planfile (dopasowanie po etykiecie
  `task:<id>`, idempotentnie), więc wybór następnego zadania korzysta z
  kontraktu runnability planfile, a backlog jest wspólny z resztą toolchainu.
- **Procesy — `urirun`.** Uruchomienie zadania może działać jako proces
  adresowany URI `agent://todo/<task>/run` z trwałym rekordem (pid, log, kod
  wyjścia) i podglądem stanu running/exit przez `urirun.host.work_runs`.
  Domyślny izolowany runner (`todo-agent run`) pozostaje synchroniczny; warstwa
  `todo-agent process` dokłada uruchamianie w tle z monitoringiem.

Instalacja z warstwami opcjonalnymi:

```bash
python -m pip install -e '.[dev,planfile,urirun]'
```

Rejestr zadań (planfile):

```bash
todo-agent tickets sync .           # rzutuj TODO/*/task.yaml na bilety planfile
todo-agent tickets list . --status open
todo-agent tickets next .           # następny bilet zgodny z kontraktem runnability
todo-agent tickets status . PLF-001 in_progress
```

Monitorowanie procesów (urirun):

```bash
todo-agent process launch . 0001_org-repo-audit --wait   # uruchom jako proces URI
todo-agent process list .                                # stan running/exit + tail logów
```

Bez zainstalowanych warstw polecenia zwracają czytelny błąd z podpowiedzią
instalacji; rdzeń (`validate`, `discover`, `run`, `scaffold`) nie wymaga żadnej
z nich. Szczegóły: `docs/integrations/planfile.md`, `docs/integrations/urirun.md`.

## Uruchomienie lokalne

Wymagany jest Python 3.11+.

```bash
python -m venv .venv
. .venv/bin/activate
python -m pip install -e '.[dev]'
make check
```

Walidacja i discovery:

```bash
todo-agent validate .
todo-agent discover . --event manual
todo-agent discover . --event schedule --now 2026-07-15T00:15:00Z
```

Test zadania audytowego bez połączenia z GitHubem:

```bash
GITHUB_ORG=example-org \
TODO_AGENT_AUDIT_FIXTURE="$PWD/TODO/0001_org-repo-audit/doctor-agent/input/sample-organization.json" \
todo-agent run . 0001_org-repo-audit
```

Wynik pojawi się w `.todo-agent-runs/<task-id>/<run-id>/` i zawiera manifest, raport zbiorczy oraz artefakty każdego agenta.

## Generowanie kompletnego zadania

Generator deterministyczny nie używa modelu:

```bash
todo-agent scaffold . \
  --title "Analiza nieodebranych wiadomości klientów" \
  --description "Zidentyfikuj wiadomości bez odpowiedzi, przygotuj szkice i zweryfikuj politykę komunikacji." \
  --type customer-support \
  --priority high \
  --scope-level external
```

Można również przekazać JSON zgodny z `schemas/task-spec.schema.json`:

```bash
todo-agent scaffold . --spec-file task-spec.json
```

Workflow `generate-task-from-nl.yml` jest opcjonalnym front-endem: GitHub Models zamienia opis na mały JSON, a ten sam deterministyczny generator tworzy pliki i otwiera draft pull request. Odpowiedź modelu nigdy nie jest wykonywana bezpośrednio.

## GitHub Actions i dostęp do organizacji

Do audytu wielu repozytoriów skonfiguruj:

- variable `GITHUB_ORG`,
- variable `TODO_AGENT_APP_CLIENT_ID`,
- secret `TODO_AGENT_APP_PRIVATE_KEY`,
- środowisko `todo-agent-apply` z wymaganymi reviewerami dla tasków `pull-request`.

Wbudowany `GITHUB_TOKEN` pozostaje wystarczający dla samego repo `todo-agent`. Odczyt lub zapis w innych repozytoriach wykorzystuje token instalacyjny GitHub App. Minimalne uprawnienia są opisane w `docs/github-app.md`.

## Standard repozytorium docelowego

Każdy projekt powinien zawierać co najmniej:

- `README.md` — cel, instalacja, użycie i utrzymanie,
- `TODO.md` — wyłącznie aktywne zadania,
- `CHANGELOG.md` — `[Unreleased]` oraz wpis bieżącej wersji,
- `VERSION` — pojedyncza wartość SemVer,
- `AGENTS.md` — wskazówki dla agentów i LLM,
- `PROJECT_NOTES.md` — robocze przemyślenia człowieka,
- `DECISIONS.md` lub ADR — trwałe decyzje,
- `.github/todo-agent.yml` — maszynowa konfiguracja build/test/release.

Plan bezpiecznego utworzenia brakujących plików:

```bash
todo-agent bootstrap-target /path/to/repository
```

Zapis, bez nadpisywania istniejących plików:

```bash
todo-agent bootstrap-target /path/to/repository --apply
```

Szczegółowa kolejność prac dla `doctor-agent`, `repair-agent`, `validator-agent` i pozostałych repozytoriów znajduje się w `docs/rollout.md`.

## Model bezpieczeństwa

1. Workflow z pull requesta tylko waliduje — nie uruchamia tasków ani nie otrzymuje tokenu organizacyjnego.
2. Harmonogram działa z domyślnej gałęzi i wykonuje tylko taski `ready`.
3. Kod taska jest kopiowany do izolowanego workspace; ścieżki wychodzące poza pakiet i symlinkowane entrypointy są odrzucane.
4. Repair-agent nie może pisać, dopóki task nie ma `mutation_mode: pull-request`, workflow nie otrzyma `apply_changes: true`, a chronione środowisko nie zostanie zatwierdzone.
5. Validator-agent nie współdzieli implementacji naprawy i nie poprawia wyników poprzednich agentów.
6. Sekrety są filtrowane przez allowlistę zmiennych środowiskowych i nie trafiają do artefaktów.

Więcej: `docs/security.md`.

## Cykl TODO / CHANGELOG / VERSION

- `TODO.md` pokazuje tylko aktualne działania.
- Po wykonaniu pozycja jest usuwana z aktywnego TODO i opisywana pod `[Unreleased]` w `CHANGELOG.md`.
- Przy wydaniu `[Unreleased]` staje się sekcją wersji, następnie aktualizowany jest `VERSION` i tworzona jest nowa pusta sekcja `[Unreleased]`.
- Nie zwiększaj wersji tylko dlatego, że LLM zmienił dokumentację; decyzja wersjonowania należy do właściciela wydania.
