ifuri-todo-agent 0.6.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (34) hide show
  1. ifuri_todo_agent-0.6.0/LICENSE +21 -0
  2. ifuri_todo_agent-0.6.0/PKG-INFO +233 -0
  3. ifuri_todo_agent-0.6.0/README.md +212 -0
  4. ifuri_todo_agent-0.6.0/pyproject.toml +49 -0
  5. ifuri_todo_agent-0.6.0/setup.cfg +4 -0
  6. ifuri_todo_agent-0.6.0/src/ifuri_todo_agent.egg-info/PKG-INFO +233 -0
  7. ifuri_todo_agent-0.6.0/src/ifuri_todo_agent.egg-info/SOURCES.txt +32 -0
  8. ifuri_todo_agent-0.6.0/src/ifuri_todo_agent.egg-info/dependency_links.txt +1 -0
  9. ifuri_todo_agent-0.6.0/src/ifuri_todo_agent.egg-info/entry_points.txt +2 -0
  10. ifuri_todo_agent-0.6.0/src/ifuri_todo_agent.egg-info/requires.txt +13 -0
  11. ifuri_todo_agent-0.6.0/src/ifuri_todo_agent.egg-info/top_level.txt +1 -0
  12. ifuri_todo_agent-0.6.0/src/todo_agent/__init__.py +12 -0
  13. ifuri_todo_agent-0.6.0/src/todo_agent/__main__.py +3 -0
  14. ifuri_todo_agent-0.6.0/src/todo_agent/bootstrap.py +114 -0
  15. ifuri_todo_agent-0.6.0/src/todo_agent/cli.py +247 -0
  16. ifuri_todo_agent-0.6.0/src/todo_agent/config.py +54 -0
  17. ifuri_todo_agent-0.6.0/src/todo_agent/cron.py +99 -0
  18. ifuri_todo_agent-0.6.0/src/todo_agent/discovery.py +61 -0
  19. ifuri_todo_agent-0.6.0/src/todo_agent/planfile_backend.py +175 -0
  20. ifuri_todo_agent-0.6.0/src/todo_agent/process.py +187 -0
  21. ifuri_todo_agent-0.6.0/src/todo_agent/reporting.py +47 -0
  22. ifuri_todo_agent-0.6.0/src/todo_agent/runner.py +482 -0
  23. ifuri_todo_agent-0.6.0/src/todo_agent/scaffold.py +219 -0
  24. ifuri_todo_agent-0.6.0/src/todo_agent/schema.py +219 -0
  25. ifuri_todo_agent-0.6.0/src/todo_agent/security.py +83 -0
  26. ifuri_todo_agent-0.6.0/src/todo_agent/target.py +78 -0
  27. ifuri_todo_agent-0.6.0/tests/test_bootstrap_target.py +26 -0
  28. ifuri_todo_agent-0.6.0/tests/test_cron.py +44 -0
  29. ifuri_todo_agent-0.6.0/tests/test_planfile_backend.py +65 -0
  30. ifuri_todo_agent-0.6.0/tests/test_process.py +73 -0
  31. ifuri_todo_agent-0.6.0/tests/test_runner.py +37 -0
  32. ifuri_todo_agent-0.6.0/tests/test_scaffold.py +52 -0
  33. ifuri_todo_agent-0.6.0/tests/test_schema_and_discovery.py +43 -0
  34. ifuri_todo_agent-0.6.0/tests/test_security.py +39 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 todo-agent maintainers
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,233 @@
1
+ Metadata-Version: 2.4
2
+ Name: ifuri-todo-agent
3
+ Version: 0.6.0
4
+ Summary: Central task registry and deterministic three-agent orchestrator for doctor-agent, repair-agent and validator-agent.
5
+ Author: todo-agent maintainers
6
+ License: MIT
7
+ Requires-Python: >=3.11
8
+ Description-Content-Type: text/markdown
9
+ License-File: LICENSE
10
+ Requires-Dist: jsonschema<5,>=4.23
11
+ Requires-Dist: PyYAML<7,>=6.0.2
12
+ Provides-Extra: dev
13
+ Requires-Dist: pytest<10,>=8.3; extra == "dev"
14
+ Requires-Dist: pytest-cov<7,>=6; extra == "dev"
15
+ Requires-Dist: ruff<1,>=0.12; extra == "dev"
16
+ Provides-Extra: planfile
17
+ Requires-Dist: planfile>=0.1.111; extra == "planfile"
18
+ Provides-Extra: urirun
19
+ Requires-Dist: urirun>=0.4.190; extra == "urirun"
20
+ Dynamic: license-file
21
+
22
+ # todo-agent
23
+
24
+ `todo-agent` jest centralnym rejestrem pakietów zadań i deterministyczną warstwą orkiestracji dla trzech istniejących wykonawców:
25
+
26
+ - **doctor-agent** — diagnoza i dowody, bez naprawiania systemu,
27
+ - **repair-agent** — plan lub kontrolowana zmiana przez pull request,
28
+ - **validator-agent** — niezależna walidacja diagnozy, planu i rezultatów.
29
+
30
+ Repozytorium nie zastępuje tych agentów. Stanowi **control plane**:
31
+ 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ą.
32
+
33
+ ## Najważniejsze właściwości
34
+
35
+ - jedna, walidowana definicja `task.yaml`,
36
+ - katalog per zadanie i per agent: `TODO/<id>/<agent>/...`,
37
+ - sekwencja `doctor → repair → validator`,
38
+ - izolowany katalog każdego uruchomienia,
39
+ - ścisłe kontrakty JSON Schema dla wyników agentów,
40
+ - planowanie harmonogramu z timezone zapisanym w zadaniu,
41
+ - domyślny tryb bez zapisu; mutacje wyłącznie jako pull request po zatwierdzeniu środowiska,
42
+ - uwierzytelnianie między repozytoriami krótkotrwałym tokenem GitHub App,
43
+ - deterministyczne generowanie scaffoldów oraz opcjonalne wejście NL przez GitHub Models,
44
+ - brak obowiązkowej zależności od płatnego GitHub Copilot/Codex,
45
+ - opcjonalny rejestr zadań na `planfile` (`todo-agent tickets`),
46
+ - opcjonalne monitorowanie procesów na `urirun` (`todo-agent process`).
47
+
48
+ ## Struktura repozytorium
49
+
50
+ ```text
51
+ .
52
+ ├── TODO/
53
+ │ └── 0001_org-repo-audit/
54
+ │ ├── task.yaml
55
+ │ ├── README.md
56
+ │ ├── doctor-agent/{README.md,run.py,input/,output/,logs/}
57
+ │ ├── repair-agent/{README.md,run.py,input/,output/,logs/}
58
+ │ └── validator-agent/{README.md,run.py,input/,output/,logs/}
59
+ ├── schemas/ # kontrakty zadań, agentów i repo docelowych
60
+ ├── src/todo_agent/ # discovery, walidacja, runner, scaffold i bootstrap
61
+ ├── scripts/ # cienkie entrypointy do CI
62
+ ├── templates/ # czytelne szablony dla ludzi
63
+ ├── docs/ # architektura, bezpieczeństwo i plan wdrożenia
64
+ └── .github/workflows/ # CI, orkiestrator, ręczne uruchomienie i generator NL
65
+ ```
66
+
67
+ ## Pakiet zadania
68
+
69
+ `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.
70
+
71
+ ```text
72
+ TODO/0042_customer-mail-triage/
73
+ ├── task.yaml
74
+ ├── README.md
75
+ ├── doctor-agent/
76
+ │ ├── README.md
77
+ │ ├── run.py
78
+ │ ├── input/
79
+ │ ├── output/
80
+ │ └── logs/
81
+ ├── repair-agent/
82
+ └── validator-agent/
83
+ ```
84
+
85
+ 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.
86
+
87
+ ## Rejestr zadań (planfile) i procesy (urirun)
88
+
89
+ todo-agent działa w oparciu o **listę zadań** i **monitorowanie procesów**, ale
90
+ oba filary są od siebie oddzielone i obie zależności są opcjonalne:
91
+
92
+ - **Lista zadań — `planfile`.** Kontraktem wykonania pozostaje
93
+ `TODO/<id>/task.yaml`, natomiast rejestrem/backlogiem jest store `planfile`.
94
+ Każde zadanie jest rzutowane na bilet planfile (dopasowanie po etykiecie
95
+ `task:<id>`, idempotentnie), więc wybór następnego zadania korzysta z
96
+ kontraktu runnability planfile, a backlog jest wspólny z resztą toolchainu.
97
+ - **Procesy — `urirun`.** Uruchomienie zadania może działać jako proces
98
+ adresowany URI `agent://todo/<task>/run` z trwałym rekordem (pid, log, kod
99
+ wyjścia) i podglądem stanu running/exit przez `urirun.host.work_runs`.
100
+ Domyślny izolowany runner (`todo-agent run`) pozostaje synchroniczny; warstwa
101
+ `todo-agent process` dokłada uruchamianie w tle z monitoringiem.
102
+
103
+ Instalacja z warstwami opcjonalnymi:
104
+
105
+ ```bash
106
+ python -m pip install -e '.[dev,planfile,urirun]'
107
+ ```
108
+
109
+ Rejestr zadań (planfile):
110
+
111
+ ```bash
112
+ todo-agent tickets sync . # rzutuj TODO/*/task.yaml na bilety planfile
113
+ todo-agent tickets list . --status open
114
+ todo-agent tickets next . # następny bilet zgodny z kontraktem runnability
115
+ todo-agent tickets status . PLF-001 in_progress
116
+ ```
117
+
118
+ Monitorowanie procesów (urirun):
119
+
120
+ ```bash
121
+ todo-agent process launch . 0001_org-repo-audit --wait # uruchom jako proces URI
122
+ todo-agent process list . # stan running/exit + tail logów
123
+ ```
124
+
125
+ Bez zainstalowanych warstw polecenia zwracają czytelny błąd z podpowiedzią
126
+ instalacji; rdzeń (`validate`, `discover`, `run`, `scaffold`) nie wymaga żadnej
127
+ z nich. Szczegóły: `docs/integrations/planfile.md`, `docs/integrations/urirun.md`.
128
+
129
+ ## Uruchomienie lokalne
130
+
131
+ Wymagany jest Python 3.11+.
132
+
133
+ ```bash
134
+ python -m venv .venv
135
+ . .venv/bin/activate
136
+ python -m pip install -e '.[dev]'
137
+ make check
138
+ ```
139
+
140
+ Walidacja i discovery:
141
+
142
+ ```bash
143
+ todo-agent validate .
144
+ todo-agent discover . --event manual
145
+ todo-agent discover . --event schedule --now 2026-07-15T00:15:00Z
146
+ ```
147
+
148
+ Test zadania audytowego bez połączenia z GitHubem:
149
+
150
+ ```bash
151
+ GITHUB_ORG=example-org \
152
+ TODO_AGENT_AUDIT_FIXTURE="$PWD/TODO/0001_org-repo-audit/doctor-agent/input/sample-organization.json" \
153
+ todo-agent run . 0001_org-repo-audit
154
+ ```
155
+
156
+ Wynik pojawi się w `.todo-agent-runs/<task-id>/<run-id>/` i zawiera manifest, raport zbiorczy oraz artefakty każdego agenta.
157
+
158
+ ## Generowanie kompletnego zadania
159
+
160
+ Generator deterministyczny nie używa modelu:
161
+
162
+ ```bash
163
+ todo-agent scaffold . \
164
+ --title "Analiza nieodebranych wiadomości klientów" \
165
+ --description "Zidentyfikuj wiadomości bez odpowiedzi, przygotuj szkice i zweryfikuj politykę komunikacji." \
166
+ --type customer-support \
167
+ --priority high \
168
+ --scope-level external
169
+ ```
170
+
171
+ Można również przekazać JSON zgodny z `schemas/task-spec.schema.json`:
172
+
173
+ ```bash
174
+ todo-agent scaffold . --spec-file task-spec.json
175
+ ```
176
+
177
+ 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.
178
+
179
+ ## GitHub Actions i dostęp do organizacji
180
+
181
+ Do audytu wielu repozytoriów skonfiguruj:
182
+
183
+ - variable `GITHUB_ORG`,
184
+ - variable `TODO_AGENT_APP_CLIENT_ID`,
185
+ - secret `TODO_AGENT_APP_PRIVATE_KEY`,
186
+ - środowisko `todo-agent-apply` z wymaganymi reviewerami dla tasków `pull-request`.
187
+
188
+ 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`.
189
+
190
+ ## Standard repozytorium docelowego
191
+
192
+ Każdy projekt powinien zawierać co najmniej:
193
+
194
+ - `README.md` — cel, instalacja, użycie i utrzymanie,
195
+ - `TODO.md` — wyłącznie aktywne zadania,
196
+ - `CHANGELOG.md` — `[Unreleased]` oraz wpis bieżącej wersji,
197
+ - `VERSION` — pojedyncza wartość SemVer,
198
+ - `AGENTS.md` — wskazówki dla agentów i LLM,
199
+ - `PROJECT_NOTES.md` — robocze przemyślenia człowieka,
200
+ - `DECISIONS.md` lub ADR — trwałe decyzje,
201
+ - `.github/todo-agent.yml` — maszynowa konfiguracja build/test/release.
202
+
203
+ Plan bezpiecznego utworzenia brakujących plików:
204
+
205
+ ```bash
206
+ todo-agent bootstrap-target /path/to/repository
207
+ ```
208
+
209
+ Zapis, bez nadpisywania istniejących plików:
210
+
211
+ ```bash
212
+ todo-agent bootstrap-target /path/to/repository --apply
213
+ ```
214
+
215
+ Szczegółowa kolejność prac dla `doctor-agent`, `repair-agent`, `validator-agent` i pozostałych repozytoriów znajduje się w `docs/rollout.md`.
216
+
217
+ ## Model bezpieczeństwa
218
+
219
+ 1. Workflow z pull requesta tylko waliduje — nie uruchamia tasków ani nie otrzymuje tokenu organizacyjnego.
220
+ 2. Harmonogram działa z domyślnej gałęzi i wykonuje tylko taski `ready`.
221
+ 3. Kod taska jest kopiowany do izolowanego workspace; ścieżki wychodzące poza pakiet i symlinkowane entrypointy są odrzucane.
222
+ 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.
223
+ 5. Validator-agent nie współdzieli implementacji naprawy i nie poprawia wyników poprzednich agentów.
224
+ 6. Sekrety są filtrowane przez allowlistę zmiennych środowiskowych i nie trafiają do artefaktów.
225
+
226
+ Więcej: `docs/security.md`.
227
+
228
+ ## Cykl TODO / CHANGELOG / VERSION
229
+
230
+ - `TODO.md` pokazuje tylko aktualne działania.
231
+ - Po wykonaniu pozycja jest usuwana z aktywnego TODO i opisywana pod `[Unreleased]` w `CHANGELOG.md`.
232
+ - Przy wydaniu `[Unreleased]` staje się sekcją wersji, następnie aktualizowany jest `VERSION` i tworzona jest nowa pusta sekcja `[Unreleased]`.
233
+ - Nie zwiększaj wersji tylko dlatego, że LLM zmienił dokumentację; decyzja wersjonowania należy do właściciela wydania.
@@ -0,0 +1,212 @@
1
+ # todo-agent
2
+
3
+ `todo-agent` jest centralnym rejestrem pakietów zadań i deterministyczną warstwą orkiestracji dla trzech istniejących wykonawców:
4
+
5
+ - **doctor-agent** — diagnoza i dowody, bez naprawiania systemu,
6
+ - **repair-agent** — plan lub kontrolowana zmiana przez pull request,
7
+ - **validator-agent** — niezależna walidacja diagnozy, planu i rezultatów.
8
+
9
+ Repozytorium nie zastępuje tych agentów. Stanowi **control plane**:
10
+ 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ą.
11
+
12
+ ## Najważniejsze właściwości
13
+
14
+ - jedna, walidowana definicja `task.yaml`,
15
+ - katalog per zadanie i per agent: `TODO/<id>/<agent>/...`,
16
+ - sekwencja `doctor → repair → validator`,
17
+ - izolowany katalog każdego uruchomienia,
18
+ - ścisłe kontrakty JSON Schema dla wyników agentów,
19
+ - planowanie harmonogramu z timezone zapisanym w zadaniu,
20
+ - domyślny tryb bez zapisu; mutacje wyłącznie jako pull request po zatwierdzeniu środowiska,
21
+ - uwierzytelnianie między repozytoriami krótkotrwałym tokenem GitHub App,
22
+ - deterministyczne generowanie scaffoldów oraz opcjonalne wejście NL przez GitHub Models,
23
+ - brak obowiązkowej zależności od płatnego GitHub Copilot/Codex,
24
+ - opcjonalny rejestr zadań na `planfile` (`todo-agent tickets`),
25
+ - opcjonalne monitorowanie procesów na `urirun` (`todo-agent process`).
26
+
27
+ ## Struktura repozytorium
28
+
29
+ ```text
30
+ .
31
+ ├── TODO/
32
+ │ └── 0001_org-repo-audit/
33
+ │ ├── task.yaml
34
+ │ ├── README.md
35
+ │ ├── doctor-agent/{README.md,run.py,input/,output/,logs/}
36
+ │ ├── repair-agent/{README.md,run.py,input/,output/,logs/}
37
+ │ └── validator-agent/{README.md,run.py,input/,output/,logs/}
38
+ ├── schemas/ # kontrakty zadań, agentów i repo docelowych
39
+ ├── src/todo_agent/ # discovery, walidacja, runner, scaffold i bootstrap
40
+ ├── scripts/ # cienkie entrypointy do CI
41
+ ├── templates/ # czytelne szablony dla ludzi
42
+ ├── docs/ # architektura, bezpieczeństwo i plan wdrożenia
43
+ └── .github/workflows/ # CI, orkiestrator, ręczne uruchomienie i generator NL
44
+ ```
45
+
46
+ ## Pakiet zadania
47
+
48
+ `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.
49
+
50
+ ```text
51
+ TODO/0042_customer-mail-triage/
52
+ ├── task.yaml
53
+ ├── README.md
54
+ ├── doctor-agent/
55
+ │ ├── README.md
56
+ │ ├── run.py
57
+ │ ├── input/
58
+ │ ├── output/
59
+ │ └── logs/
60
+ ├── repair-agent/
61
+ └── validator-agent/
62
+ ```
63
+
64
+ 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.
65
+
66
+ ## Rejestr zadań (planfile) i procesy (urirun)
67
+
68
+ todo-agent działa w oparciu o **listę zadań** i **monitorowanie procesów**, ale
69
+ oba filary są od siebie oddzielone i obie zależności są opcjonalne:
70
+
71
+ - **Lista zadań — `planfile`.** Kontraktem wykonania pozostaje
72
+ `TODO/<id>/task.yaml`, natomiast rejestrem/backlogiem jest store `planfile`.
73
+ Każde zadanie jest rzutowane na bilet planfile (dopasowanie po etykiecie
74
+ `task:<id>`, idempotentnie), więc wybór następnego zadania korzysta z
75
+ kontraktu runnability planfile, a backlog jest wspólny z resztą toolchainu.
76
+ - **Procesy — `urirun`.** Uruchomienie zadania może działać jako proces
77
+ adresowany URI `agent://todo/<task>/run` z trwałym rekordem (pid, log, kod
78
+ wyjścia) i podglądem stanu running/exit przez `urirun.host.work_runs`.
79
+ Domyślny izolowany runner (`todo-agent run`) pozostaje synchroniczny; warstwa
80
+ `todo-agent process` dokłada uruchamianie w tle z monitoringiem.
81
+
82
+ Instalacja z warstwami opcjonalnymi:
83
+
84
+ ```bash
85
+ python -m pip install -e '.[dev,planfile,urirun]'
86
+ ```
87
+
88
+ Rejestr zadań (planfile):
89
+
90
+ ```bash
91
+ todo-agent tickets sync . # rzutuj TODO/*/task.yaml na bilety planfile
92
+ todo-agent tickets list . --status open
93
+ todo-agent tickets next . # następny bilet zgodny z kontraktem runnability
94
+ todo-agent tickets status . PLF-001 in_progress
95
+ ```
96
+
97
+ Monitorowanie procesów (urirun):
98
+
99
+ ```bash
100
+ todo-agent process launch . 0001_org-repo-audit --wait # uruchom jako proces URI
101
+ todo-agent process list . # stan running/exit + tail logów
102
+ ```
103
+
104
+ Bez zainstalowanych warstw polecenia zwracają czytelny błąd z podpowiedzią
105
+ instalacji; rdzeń (`validate`, `discover`, `run`, `scaffold`) nie wymaga żadnej
106
+ z nich. Szczegóły: `docs/integrations/planfile.md`, `docs/integrations/urirun.md`.
107
+
108
+ ## Uruchomienie lokalne
109
+
110
+ Wymagany jest Python 3.11+.
111
+
112
+ ```bash
113
+ python -m venv .venv
114
+ . .venv/bin/activate
115
+ python -m pip install -e '.[dev]'
116
+ make check
117
+ ```
118
+
119
+ Walidacja i discovery:
120
+
121
+ ```bash
122
+ todo-agent validate .
123
+ todo-agent discover . --event manual
124
+ todo-agent discover . --event schedule --now 2026-07-15T00:15:00Z
125
+ ```
126
+
127
+ Test zadania audytowego bez połączenia z GitHubem:
128
+
129
+ ```bash
130
+ GITHUB_ORG=example-org \
131
+ TODO_AGENT_AUDIT_FIXTURE="$PWD/TODO/0001_org-repo-audit/doctor-agent/input/sample-organization.json" \
132
+ todo-agent run . 0001_org-repo-audit
133
+ ```
134
+
135
+ Wynik pojawi się w `.todo-agent-runs/<task-id>/<run-id>/` i zawiera manifest, raport zbiorczy oraz artefakty każdego agenta.
136
+
137
+ ## Generowanie kompletnego zadania
138
+
139
+ Generator deterministyczny nie używa modelu:
140
+
141
+ ```bash
142
+ todo-agent scaffold . \
143
+ --title "Analiza nieodebranych wiadomości klientów" \
144
+ --description "Zidentyfikuj wiadomości bez odpowiedzi, przygotuj szkice i zweryfikuj politykę komunikacji." \
145
+ --type customer-support \
146
+ --priority high \
147
+ --scope-level external
148
+ ```
149
+
150
+ Można również przekazać JSON zgodny z `schemas/task-spec.schema.json`:
151
+
152
+ ```bash
153
+ todo-agent scaffold . --spec-file task-spec.json
154
+ ```
155
+
156
+ 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.
157
+
158
+ ## GitHub Actions i dostęp do organizacji
159
+
160
+ Do audytu wielu repozytoriów skonfiguruj:
161
+
162
+ - variable `GITHUB_ORG`,
163
+ - variable `TODO_AGENT_APP_CLIENT_ID`,
164
+ - secret `TODO_AGENT_APP_PRIVATE_KEY`,
165
+ - środowisko `todo-agent-apply` z wymaganymi reviewerami dla tasków `pull-request`.
166
+
167
+ 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`.
168
+
169
+ ## Standard repozytorium docelowego
170
+
171
+ Każdy projekt powinien zawierać co najmniej:
172
+
173
+ - `README.md` — cel, instalacja, użycie i utrzymanie,
174
+ - `TODO.md` — wyłącznie aktywne zadania,
175
+ - `CHANGELOG.md` — `[Unreleased]` oraz wpis bieżącej wersji,
176
+ - `VERSION` — pojedyncza wartość SemVer,
177
+ - `AGENTS.md` — wskazówki dla agentów i LLM,
178
+ - `PROJECT_NOTES.md` — robocze przemyślenia człowieka,
179
+ - `DECISIONS.md` lub ADR — trwałe decyzje,
180
+ - `.github/todo-agent.yml` — maszynowa konfiguracja build/test/release.
181
+
182
+ Plan bezpiecznego utworzenia brakujących plików:
183
+
184
+ ```bash
185
+ todo-agent bootstrap-target /path/to/repository
186
+ ```
187
+
188
+ Zapis, bez nadpisywania istniejących plików:
189
+
190
+ ```bash
191
+ todo-agent bootstrap-target /path/to/repository --apply
192
+ ```
193
+
194
+ Szczegółowa kolejność prac dla `doctor-agent`, `repair-agent`, `validator-agent` i pozostałych repozytoriów znajduje się w `docs/rollout.md`.
195
+
196
+ ## Model bezpieczeństwa
197
+
198
+ 1. Workflow z pull requesta tylko waliduje — nie uruchamia tasków ani nie otrzymuje tokenu organizacyjnego.
199
+ 2. Harmonogram działa z domyślnej gałęzi i wykonuje tylko taski `ready`.
200
+ 3. Kod taska jest kopiowany do izolowanego workspace; ścieżki wychodzące poza pakiet i symlinkowane entrypointy są odrzucane.
201
+ 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.
202
+ 5. Validator-agent nie współdzieli implementacji naprawy i nie poprawia wyników poprzednich agentów.
203
+ 6. Sekrety są filtrowane przez allowlistę zmiennych środowiskowych i nie trafiają do artefaktów.
204
+
205
+ Więcej: `docs/security.md`.
206
+
207
+ ## Cykl TODO / CHANGELOG / VERSION
208
+
209
+ - `TODO.md` pokazuje tylko aktualne działania.
210
+ - Po wykonaniu pozycja jest usuwana z aktywnego TODO i opisywana pod `[Unreleased]` w `CHANGELOG.md`.
211
+ - Przy wydaniu `[Unreleased]` staje się sekcją wersji, następnie aktualizowany jest `VERSION` i tworzona jest nowa pusta sekcja `[Unreleased]`.
212
+ - Nie zwiększaj wersji tylko dlatego, że LLM zmienił dokumentację; decyzja wersjonowania należy do właściciela wydania.
@@ -0,0 +1,49 @@
1
+ [build-system]
2
+ requires = ["setuptools>=77", "wheel"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "ifuri-todo-agent"
7
+ version = "0.6.0"
8
+ description = "Central task registry and deterministic three-agent orchestrator for doctor-agent, repair-agent and validator-agent."
9
+ readme = "README.md"
10
+ requires-python = ">=3.11"
11
+ license = {text = "MIT"}
12
+ authors = [{name = "todo-agent maintainers"}]
13
+ dependencies = [
14
+ "jsonschema>=4.23,<5",
15
+ "PyYAML>=6.0.2,<7"
16
+ ]
17
+
18
+ [project.optional-dependencies]
19
+ dev = [
20
+ "pytest>=8.3,<10",
21
+ "pytest-cov>=6,<7",
22
+ "ruff>=0.12,<1"
23
+ ]
24
+ # planfile-backed task registry (todo-agent tickets ...)
25
+ planfile = [
26
+ "planfile>=0.1.111"
27
+ ]
28
+ # urirun-backed process monitoring (todo-agent process ...)
29
+ urirun = [
30
+ "urirun>=0.4.190"
31
+ ]
32
+
33
+ [project.scripts]
34
+ todo-agent = "todo_agent.cli:main"
35
+
36
+ [tool.setuptools.packages.find]
37
+ where = ["src"]
38
+
39
+ [tool.pytest.ini_options]
40
+ testpaths = ["tests"]
41
+ addopts = "-ra --strict-markers"
42
+
43
+ [tool.ruff]
44
+ target-version = "py311"
45
+ line-length = 120
46
+
47
+ [tool.ruff.lint]
48
+ select = ["E", "F", "I", "B", "UP", "SIM"]
49
+ ignore = ["E501"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+