diff --git a/docs/superpowers/plans/2026-10-13-bridge-reliability-agent.md b/docs/superpowers/plans/2026-10-13-bridge-reliability-agent.md new file mode 100644 index 0000000..37a79fd --- /dev/null +++ b/docs/superpowers/plans/2026-10-13-bridge-reliability-agent.md @@ -0,0 +1,265 @@ +# bridge-reliability — агент: план реализации + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** после перезапуска агент соблюдает темп Jira (время последнего вызова восстанавливается из журнала, пауза при +восстановлении не обнуляется) и не пишет `claimed` в журнал повторно; версия агента 3. + +**Architecture:** всё в `src/agent.py`: `Journal.last_at()` даёт самое позднее время записи; `Runner.restore_pace()` +один раз в начале `loop()` переводит его в `JiraClient.last_call_at`; `Runner.execute(cmd, journal_claimed=True)`; +`Runner.recover()` больше не обнуляет `pause_seconds` и вызывает `execute(cmd, journal_claimed=False)`. + +**Tech Stack:** Python 3.9, только стандартная библиотека, `unittest`. + +**Spec:** `../jira-hub/openspec/changes/bridge-reliability/` (ветка `feat/9-bridge-reliability` в jira-hub; +`specs/agent/spec.md` — требования «Цикл выполнения», «Журнал на диске и восстановление», «Ограничение темпа и 429», +«Доставка и запуск»; `design.md` — решения 9–11). + +## Global Constraints + +- Python ≥ 3.9, только stdlib (`tests/test_py39.py` проверяет синтаксис и импорты). +- Тесты: `/usr/bin/python3 -W error::ResourceWarning -m unittest discover -s tests -t .` из корня worktree — зелёным + считается только весь набор (до начала: 133 OK). +- Тела запросов к хабу не меняются. +- Комментарии, сообщения лога и коммитов — по-русски; коммиты через + `git -C /Users/andrey.epifancev/projects/awp-ca/jira-agent/.wt/reliability …`, суффикс `(#9)`, строка + `Co-Authored-By: Claude Opus 5.5 `. +- Решения без обсуждения — в `openspec/changes/bridge-reliability/design.md` этого репозитория (создать при первом + решении: заголовок `# bridge-reliability — решения агента`, ссылка на спеку хаба, таблица + `## Decisions made without discussion` с колонками Дата | Решение | Обоснование | Цена ошибки), маркер `R-n`. + +## Review Focus + +1. Журнал со временем записи в будущем (часы виртуалки сдвинулись назад после записи) — не ставить паузу больше + положенной и не падать: оценка игнорируется — тест в Task 1. +2. Журнал с битой строкой или записью без `at` — восстановление темпа берёт годные записи и не падает — тест в Task 1. +3. Тесты, где `last_call_at` задан вручную до `loop()`, — восстановление из журнала его не перетирает — тест в Task 1. +4. Восстановление команды, выданной до остановки, при пустом журнале кроме этой записи — пауза отсчитывается от + `claimed`/`started` этой записи, а не обнуляется — тест в Task 2. +5. Обычная выдача (не восстановление) по-прежнему пишет `claimed` до паузы (R-9) — существующий + `test_processes_queue` остаётся зелёным, Task 2. + +--- + +### Task 1: Время последнего вызова Jira восстанавливается из журнала + +**Files:** +- Modify: `src/agent.py` (`Journal.last_at`, `Runner.restore_pace`, `Runner.loop`) +- Test: `tests/test_runner.py`, `tests/test_journal.py` + +**Interfaces:** +- Produces: `Journal.last_at() -> Optional[datetime]` (aware UTC, самое позднее `at` среди годных записей или `None`); + `Runner.restore_pace() -> None` (ставит `jira.last_call_at`/`last_call_iso`, если они пусты и в журнале есть время не + из будущего). + +- [ ] **Step 1: Write the failing tests** + +`tests/test_journal.py` (в существующий класс тестов журнала; имена `self.path`/`self.journal` взять из его `setUp`; +при необходимости `from datetime import datetime, timedelta, timezone`): + +```python + def test_last_at_is_latest_record_time(self): + self.assertIsNone(self.journal.last_at()) + self.journal.append({"kind": "claimed", "command_id": 1, "at": "2026-10-13T10:00:00+00:00"}) + self.journal.append({"kind": "finished", "command_id": 1, "at": "2026-10-13T10:05:00+00:00"}) + self.journal.append({"kind": "acked", "command_id": 1, "at": "2026-10-13T10:04:00+00:00"}) + self.assertEqual(self.journal.last_at(), datetime(2026, 10, 13, 10, 5, tzinfo=timezone.utc)) + + def test_last_at_skips_bad_and_missing_times(self): + self.journal.append({"kind": "claimed", "command_id": 1, "at": "2026-10-13T10:00:00+00:00"}) + self.journal.append({"kind": "started", "command_id": 1, "at": "не время"}) + self.journal.append({"kind": "started", "command_id": 1, "at": "2026-10-13T11:00:00"}) # без зоны — пропуск + with open(self.journal.path, "a", encoding="utf-8") as f: + f.write("битая строка\n") + self.assertEqual(self.journal.last_at(), datetime(2026, 10, 13, 10, 0, tzinfo=timezone.utc)) +``` + +`tests/test_runner.py` (класс `RunnerTest`; импорт `from datetime import datetime, timedelta, timezone` в начало файла): + +```python + def test_restart_pace_from_old_finished(self): + at = (datetime.now(timezone.utc) - timedelta(seconds=10)).replace(microsecond=0).isoformat() + self.journal.append({"kind": "finished", "command_id": 99, "status": "done", "result": None, "error": None, + "jira_calls": 1, "rate_limited": 0, "at": at}) + self.journal.append({"kind": "acked", "command_id": 99, "at": at}) + self.hub.enqueue("ensure_fields", {"key": "AURORA-1", "duedate": "2026-10-23"}, pause=30) + self.runner.loop() + self.assertAlmostEqual(sum(self.sleeps), 20, delta=1.5) + + def test_future_journal_time_ignored(self): + at = (datetime.now(timezone.utc) + timedelta(hours=1)).replace(microsecond=0).isoformat() + self.journal.append({"kind": "acked", "command_id": 99, "at": at}) + self.hub.enqueue("ensure_fields", {"key": "AURORA-1", "duedate": "2026-10-23"}, pause=30) + self.runner.loop() + self.assertEqual(self.sleeps, []) # время из будущего — как пустой журнал + self.assertEqual(self.hub.results[1]["status"], "done") + + def test_restore_pace_keeps_existing_last_call(self): + at = (datetime.now(timezone.utc) - timedelta(seconds=100)).replace(microsecond=0).isoformat() + self.journal.append({"kind": "acked", "command_id": 99, "at": at}) + mark = time.monotonic() + self.runner.jira.last_call_at = mark + self.runner.restore_pace() + self.assertEqual(self.runner.jira.last_call_at, mark) +``` + +- [ ] **Step 2: Run tests to verify they fail** + +Run: `/usr/bin/python3 -W error::ResourceWarning -m unittest tests.test_journal tests.test_runner` +Expected: FAIL — нет `Journal.last_at`, нет `Runner.restore_pace`, пауза после перезапуска 0. + +- [ ] **Step 3: Implement** — `src/agent.py`: + +В класс `Journal` после `records`: + +```python + def last_at(self) -> Optional[datetime]: + """Самое позднее время записи журнала (UTC). Записи без времени или с непонятным временем пропускаются.""" + latest = None + for r in self.records(): + try: + t = datetime.fromisoformat(r["at"]) + except (KeyError, TypeError, ValueError): + continue + if t.tzinfo is None: + continue + if latest is None or t > latest: + latest = t + return latest +``` + +В класс `Runner` после `load_settings`: + +```python + def restore_pace(self) -> None: + """После перезапуска время последнего вызова Jira неизвестно (живёт в памяти). Берём самое позднее время записи + журнала: finished пишется сразу после последнего вызова команды, оценка не раньше настоящего вызова (M-9).""" + if self.jira.last_call_at is not None: + return + at = self.journal.last_at() + if at is None: + return + ago = (datetime.now(timezone.utc) - at).total_seconds() + if ago < 0: + log("журнал: время последней записи в будущем (%s) — темп не восстанавливаю" % at.isoformat()) + return + self.jira.last_call_at = time.monotonic() - ago + self.jira.last_call_iso = at.astimezone(timezone.utc).replace(microsecond=0).isoformat() + log("темп: последний вызов Jira не позже %s (по журналу)" % self.jira.last_call_iso) +``` + +В `loop()` первой строкой тела (до `idle, recovered = 0, False` или сразу после неё): `self.restore_pace()`. + +- [ ] **Step 4: Run tests** + +Run: полный набор (см. Global Constraints) — OK. Существующие тесты перезапуска +(`test_stop_during_pause_then_restart_executes_once`, `test_recover_unfinished_started`) остаются зелёными: `recover` +до Task 2 обнуляет `pause_seconds`, поэтому восстановленное время последнего вызова на них не влияет. + +- [ ] **Step 5: Commit** + +```bash +git -C /Users/andrey.epifancev/projects/awp-ca/jira-agent/.wt/reliability add src/agent.py tests +git -C /Users/andrey.epifancev/projects/awp-ca/jira-agent/.wt/reliability commit -m "feat(agent): время последнего вызова Jira восстанавливается из журнала после перезапуска (M-9, #9) + +Co-Authored-By: Claude Opus 5.5 " +``` + +--- + +### Task 2: Восстановление без обнуления паузы и без повторного `claimed`; версия 3 + +**Files:** +- Modify: `src/agent.py` (`AGENT_VERSION`, `Runner.execute`, `Runner.recover`, docstring про спеку в начале файла, + если он ссылается на `changes/bridge-core`) +- Modify: `README.md` (строки про «выполняет через проверку (без паузы)», «Версия … (сейчас 2)», раздел про R-9) +- Test: `tests/test_runner.py`, `tests/test_folder.py` + +**Interfaces:** +- Consumes: `Runner.restore_pace` (Task 1). +- Produces: `Runner.execute(cmd: dict, journal_claimed: bool = True) -> None`; `AGENT_VERSION = 3`. + +- [ ] **Step 1: Write the failing tests** — `tests/test_runner.py`: + +1. `test_recover_unfinished_started` — заменить проверку пауз и добавить проверку журнала: + +```python + def test_recover_unfinished_started(self): + cid = self.claim_in_flight("ensure_fields", {"key": "AURORA-1", "duedate": "2026-10-20"}, pause=99) + self.journal.started(cid) + self.runner.loop() + self.assertEqual(self.hub.results[cid]["result"], {"changed": []}) # уже так в Jira — записи нет + self.assertEqual(self.journal.unfinished_started(), []) + self.assertAlmostEqual(sum(self.sleeps), 99, delta=1) # пауза из хаба, от записи started (M-9) + self.assertEqual([r[0] for r in self.fake.writes()], []) +``` + +2. Новый тест FM-4: + +```python + def test_recover_does_not_journal_claimed_twice(self): + cid = self.claim_in_flight("ensure_fields", {"key": "AURORA-1", "duedate": "2026-10-20"}, pause=0) + self.journal.claimed(cid) + self.runner.loop() + self.assertEqual(self.kinds(), [("claimed", cid), ("started", cid), ("finished", cid), ("acked", cid)]) +``` + +3. `test_stop_during_pause_then_restart_executes_once` — последнюю проверку заменить на + `self.assertAlmostEqual(sum(self.sleeps), 5, delta=1) # пауза из хаба от записи claimed (M-9)`. +4. `tests/test_folder.py`: `test_version_is_2` → `test_version_is_3` с `self.assertEqual(agent.AGENT_VERSION, 3)`. + +- [ ] **Step 2: Run tests to verify they fail** + +Run: `/usr/bin/python3 -W error::ResourceWarning -m unittest tests.test_runner tests.test_folder` +Expected: FAIL — пауза при восстановлении 0; `claimed` в журнале дважды; версия 2. + +- [ ] **Step 3: Implement** — `src/agent.py`: + +1. `AGENT_VERSION = 3`. +2. `execute`: + +```python + def execute(self, cmd: dict, journal_claimed: bool = True) -> None: + cid = cmd["id"] + log("#%s %s %s" % (cid, cmd["type"], json.dumps(cmd.get("params"), ensure_ascii=False)[:200])) + if journal_claimed: + self.journal.claimed(cid) # сразу после claim, до паузы (R-9): остановка не теряет команду + if not self.wait_pause(cmd.get("pause_seconds")): + return + # дальше без изменений +``` + +3. `recover` — конец цикла: + +```python + log("#%s выдана до перезапуска — выполняю через проверку" % cid) + self.execute(cmd, journal_claimed=False) # claimed/started для неё уже в журнале (FM-4); пауза — из хаба (M-9) +``` + + (строка `cmd["pause_seconds"] = 0` удаляется.) +4. Если docstring модуля/справка `--help` ссылается на `jira-hub/openspec/changes/bridge-core/specs/agent/spec.md` — + заменить на `jira-hub/openspec/specs/agent/spec.md`. + +`README.md`: +- «…при следующем запуске агент запрашивает её у хаба и выполняет через проверку (без паузы).» → + «…выполняет через проверку, выдержав паузу темпа от последней записи журнала.» +- «Константа `AGENT_VERSION` в `agent.py` (сейчас 2)» → «(сейчас 3)». +- В разделе ограничений, пункт 2 (R-9): «выполняет без паузы» → «выполняет с паузой темпа (время последнего вызова Jira + берётся из журнала)». +- В раздел про паузы (строка «**Паузы.** …») дописать предложение: «После перезапуска время последнего вызова Jira + берётся из журнала (самая поздняя запись), поэтому первая команда тоже ждёт паузу.» +- Если в README есть упоминание, что хаб ждёт 10 минут / «нет ответа от агента», — заменить на довыдачу: «Если ответ на + `claim` потерян, хаб выдаст ту же команду снова при следующем `claim` (до 3 выдач).» + +- [ ] **Step 4: Run tests** + +Run: полный набор (см. Global Constraints) — OK. + +- [ ] **Step 5: Commit** + +```bash +git -C /Users/andrey.epifancev/projects/awp-ca/jira-agent/.wt/reliability add -A src tests README.md +git -C /Users/andrey.epifancev/projects/awp-ca/jira-agent/.wt/reliability commit -m "feat(agent): восстановление с паузой из хаба и без повторного claimed; версия 3 (M-9, FM-4, #9) + +Co-Authored-By: Claude Opus 5.5 " +```