# bridge-hygiene — агент: план реализации

> **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:** агент v4: сравнение текстов без различия `\r\n`/`\n`, честное время последнего вызова Jira в `claim`, полная
пауза при времени журнала в будущем, устойчивость к ответу папки с неверными типами, `prune` под блокировкой.

**Architecture:** точечные правки в `src/agent.py` (`Executor.do_ensure_fields`, `do_ensure_comment`,
`Runner.restore_pace`, `FolderTransport`, CLI `prune`); контракт с хабом не меняется.

**Tech Stack:** Python 3.9.6 (`/usr/bin/python3`), только stdlib, `unittest`.

**Spec:** `../jira-hub/.wt/hygiene/openspec/changes/bridge-hygiene/` (design.md решения 16–21, specs/agent, specs/commands);
агентские решения — `openspec/changes/bridge-hygiene/design.md` в этом репозитории.

## Global Constraints

- Рабочий каталог: `/Users/andrey.epifancev/projects/awp-ca/jira-agent/.wt/hygiene` (ветка `feat/15-bridge-hygiene`).
- Только синтаксис и stdlib Python 3.9: никаких `X | Y` в аннотациях функций, `match`, сторонних импортов.
- Весь набор: `/usr/bin/python3 -W error::ResourceWarning -m unittest discover -s tests -t .` (до начала: 141 OK).
- `AGENT_VERSION = 4`.
- Комментарии, docstring, логи и коммиты — по-русски; коммит с суффиксом `(#15)` и строкой
  `Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>`.
- Решения без обсуждения — в `openspec/changes/bridge-hygiene/design.md` этого репозитория, следующий маркер `R-12`.

## Review Focus

1. Описание в Jira `None`, а в команде `""` (или наоборот) — изменений нет, как и до правки — тест в Task 1.
2. Перезапуск с журналом, где последняя запись в будущем, и сразу Ctrl-C в паузе — пауза прерывается, команда остаётся на
   восстановление — существующий `test_stop_during_pause` (Task 2 не должен его ломать).
3. Ответ папки `{"status": true, …}` (bool — подкласс int в Python) — нечитаемый ответ, а не статус 1 — тест в Task 3.
4. `prune` при работающем агенте — отказ без изменения журнала; после остановки — работает — тест в Task 4.
5. Первый `claim` после перезапуска несёт `last_jira_call_at = null`, после первого вызова Jira — настоящее время —
   тест в Task 2.

---

### Task 1: Сравнение описания и комментария без различия переводов строк

**Files:**
- Modify: `src/agent.py` (новая `_nl` рядом с `_date`; `do_ensure_fields`, `do_ensure_comment`)
- Test: `tests/test_executor_fields.py`

**Interfaces:**
- Produces: `agent._nl(value) -> str` — `(value or "").replace("\r\n", "\n")`.

- [ ] **Step 1: Write the failing tests** — дописать в класс `ExecutorFieldsTest`:

```python
    def test_fields_description_crlf_equals_lf(self):
        self.fake.add("AURORA-1", description="а\r\nб")         # так Jira хранит текст, правленный в UI
        out = self.run_cmd("ensure_fields", key="AURORA-1", description="а\nб")
        self.assertEqual(out["result"]["changed"], [])
        out = self.run_cmd("ensure_fields", key="AURORA-1", description="а\nв")
        self.assertEqual(out["result"]["changed"], ["description"])
        self.assertEqual(self.fake.issues["AURORA-1"]["description"], "а\nв")   # отправлен текст команды как есть

    def test_fields_description_none_equals_empty(self):
        self.fake.add("AURORA-1", description=None)
        out = self.run_cmd("ensure_fields", key="AURORA-1", description="")
        self.assertEqual(out["result"]["changed"], [])

    def test_comment_crlf_equals_lf(self):
        self.fake.add("AURORA-1")
        self.fake.comments["AURORA-1"] = [{"id": "10", "body": "*Актуализация 10.10.2026.* строка1\r\nстрока2"}]
        out = self.run_cmd("ensure_comment", key="AURORA-1", marker="Актуализация 10.10.2026", body="строка1\nстрока2")
        self.assertEqual(out["result"], {"comment_id": "10", "changed": False})
```

Сверить формат элемента `fake.comments[key]` с `tests/fake_jira.py` (около строки 204) и подогнать словарь под него.

- [ ] **Step 2: Run tests to verify they fail**

Run: `/usr/bin/python3 -m unittest tests.test_executor_fields -v`
Expected: FAIL — `changed == ["description"]` для CRLF; комментарий `changed: True`.

- [ ] **Step 3: Implement** — в `src/agent.py` сразу после `_date`:

```python
def _nl(value) -> str:
    """Текст для сравнения: Jira хранит правленное в UI с \r\n, команды приходят с \n (T3.9, проверено 13.10.2026)."""
    return (value or "").replace("\r\n", "\n")
```

В `do_ensure_fields` строку сравнения описания:

```python
        if "description" in p and _nl(cur.get(self.fid("description"))) != _nl(p["description"]):
```

В `do_ensure_comment` строку проверки совпадения:

```python
        if existing and _nl(existing.get("body")) == _nl(body):
```

- [ ] **Step 4: Run tests**

Run: `/usr/bin/python3 -W error::ResourceWarning -m unittest discover -s tests -t .`
Expected: OK (включая `test_fields_description_exact_compare` — разница в завершающем `\n` по-прежнему изменение).

- [ ] **Step 5: Commit**

```bash
git add src/agent.py tests/test_executor_fields.py
git commit -m "fix(agent): описание и комментарий сравниваются без различия CRLF/LF (#15)

T3.9 (agent#4).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>"
```

---

### Task 2: Темп после перезапуска — будущее время журнала и `last_jira_call_at`

**Files:**
- Modify: `src/agent.py` (`Runner.restore_pace`)
- Modify: `tests/fake_hub.py` (запоминать тела `claim`)
- Test: `tests/test_runner.py`

**Interfaces:**
- Consumes: `JiraClient.last_call_at` (monotonic), `JiraClient.last_call_iso` (ISO UTC, ставится в `JiraClient` при
  каждом вызове Jira).
- Produces: `FakeHub.claim_bodies: list[dict]` — тела всех `POST /agent/claim` по порядку.

- [ ] **Step 1: `tests/fake_hub.py`** — в `__init__` добавить `self.claim_bodies = []`; в `route` в ветке
  `if path == "/agent/claim":` первой строкой `self.claim_bodies.append(body or {})`.

- [ ] **Step 2: Write the failing tests** — в `tests/test_runner.py` заменить `test_future_journal_time_ignored` и
  дописать новый тест:

```python
    def test_future_journal_time_means_full_pause(self):
        at = (datetime.now(timezone.utc) + timedelta(hours=2)).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.assertAlmostEqual(sum(self.sleeps), 30, delta=1.5)  # часы ушли назад — пауза полная (M-6 #12)
        self.assertEqual(self.hub.results[1]["status"], "done")

    def test_claim_after_restart_sends_no_journal_estimate(self):
        at = (datetime.now(timezone.utc) - timedelta(seconds=10)).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"})
        self.runner.loop()
        self.assertIsNone(self.hub.claim_bodies[0].get("last_jira_call_at"))     # оценка журнала — только для паузы (M-7 #12)
        self.assertIsNotNone(self.hub.claim_bodies[-1].get("last_jira_call_at"))  # после вызова Jira — настоящее время
        self.assertIsNotNone(self.runner.jira.last_call_at)
```

- [ ] **Step 3: Run tests to verify they fail**

Run: `/usr/bin/python3 -m unittest tests.test_runner -v`
Expected: FAIL — пауза 0 при будущем времени; первый `claim` несёт время журнала.

- [ ] **Step 4: Implement** — `Runner.restore_pace` целиком:

```python
    def restore_pace(self) -> None:
        """После перезапуска время последнего вызова Jira неизвестно (живёт в памяти). Берём самое позднее время записи
        журнала: finished пишется сразу после последнего вызова команды, оценка не раньше настоящего вызова (M-9).
        Время в будущем (часы ушли назад) — считаем «сейчас»: пауза полная (M-6 #12). Оценка служит только паузе:
        last_call_iso (уходит хабу в claim) ставит лишь настоящий вызов Jira (M-7 #12)."""
        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())
            ago = 0
        self.jira.last_call_at = time.monotonic() - ago
        log("темп: последний вызов Jira не позже %s (по журналу)"
            % at.astimezone(timezone.utc).replace(microsecond=0).isoformat())
```

- [ ] **Step 5: Run tests**

Run: `/usr/bin/python3 -W error::ResourceWarning -m unittest discover -s tests -t .`
Expected: OK. Если другой тест проверял `last_call_iso` после `restore_pace` — привести его к спеке (оценка в
`last_call_iso` не попадает) и записать рулинг `R-12` в design.md.

- [ ] **Step 6: Commit**

```bash
git add src/agent.py tests/fake_hub.py tests/test_runner.py
git commit -m "fix(agent): полная пауза при времени журнала в будущем, claim без оценки из журнала (#15)

M-6, M-7 (agent#12).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>"
```

---

### Task 3: Ответ папки с неверными типами; текст ошибки без «хаб: хаб»

**Files:**
- Modify: `src/agent.py` (`FolderTransport.call`, `FolderTransport._take`)
- Test: `tests/test_folder.py`

**Interfaces:**
- Consumes: `FolderTransport(root, authorization)`, `FolderTransport.BAD_JSON_WAIT`, `FolderTransport._take(path)`.

- [ ] **Step 1: Write the failing tests** — дописать в `FolderTransportTest`:

```python
    def _bad_response(self, payload):
        path = os.path.join(self.root, "resp-bad.json")
        with open(path, "w", encoding="utf-8") as f:
            json.dump(payload, f)
        ft = agent.FolderTransport(self.root, "Bearer x")
        ft.BAD_JSON_WAIT = 0.3
        return ft, path

    def test_wrong_status_type_is_unreadable(self):
        for payload in ({"id": "x", "status": "ok", "body": "{}"}, {"id": "x", "status": True, "body": "{}"},
                        {"id": "x", "status": 200, "body": 5}):
            ft, path = self._bad_response(payload)
            with self.assertRaises(ConnectionError) as e:
                ft._take(path)
            self.assertIn("нечитаемый ответ", str(e.exception))

    def test_no_answer_message_has_no_hub_prefix(self):
        hub = self.client(timeout=0.3)
        with self.assertRaises(ConnectionError) as e:
            hub.settings()
        self.assertFalse(str(e.exception).startswith("хаб"))    # цикл сам пишет «хаб: …» (O-3 agent#8)
```

- [ ] **Step 2: Run tests to verify they fail**

Run: `/usr/bin/python3 -m unittest tests.test_folder -v`
Expected: FAIL — `ValueError: invalid literal for int()` / `TypeError` вместо `ConnectionError`; текст начинается с «хаб».

- [ ] **Step 3: Implement** — в `FolderTransport._take` после проверки `if not isinstance(resp, dict): raise ValueError(...)`:

```python
                status, body = resp.get("status"), resp.get("body")
                if type(status) is not int or not (body is None or isinstance(body, str)):
                    raise ValueError("неверные типы status/body")   # bool — подкласс int, поэтому type(), не isinstance (M-2 agent#8)
```

В `FolderTransport.call` последнюю строку заменить на
`raise ConnectionError("не ответил через папку %s за %.0f с" % (self.root, timeout))`.

- [ ] **Step 4: Run tests**

Run: `/usr/bin/python3 -W error::ResourceWarning -m unittest discover -s tests -t .`
Expected: OK (тесты с «не ответил через папку» проходят — подстрока сохранена).

- [ ] **Step 5: Commit**

```bash
git add src/agent.py tests/test_folder.py
git commit -m "fix(agent): ответ папки с неверными типами — ConnectionError; лог без повтора «хаб» (#15)

M-2, O-3 (agent#8).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>"
```

---

### Task 4: `prune` под блокировкой, версия 4, README, `.gitignore`

**Files:**
- Modify: `src/agent.py` (`AGENT_VERSION`, новая `cmd_prune`, `main`)
- Modify: `README.md`, `.gitignore`, `CLAUDE.md`
- Test: `tests/test_runner.py`, `tests/test_folder.py`

**Interfaces:**
- Consumes: `agent.acquire_lock(journal_path) -> file | None`, `Journal(path).prune(days) -> int`.
- Produces: `agent.cmd_prune(journal_path: str) -> int` — 0 после очистки, 1 если журнал занят работающим агентом.

- [ ] **Step 1: Write the failing tests**

В `tests/test_runner.py` (класс `RunnerTest`):

```python
    def test_prune_refused_while_agent_runs(self):
        old = "2020-01-01T00:00:00+00:00"
        self.journal.append({"kind": "finished", "command_id": 7, "status": "done", "result": None, "error": None,
                             "jira_calls": 1, "rate_limited": 0, "at": old})
        self.journal.append({"kind": "acked", "command_id": 7, "at": old})
        held = agent.acquire_lock(self.journal.path)
        try:
            self.assertEqual(agent.cmd_prune(self.journal.path), 1)
            self.assertEqual(len(self.journal.records()), 2)        # журнал не тронут (T2.3 agent#4)
        finally:
            held.close()
        self.assertEqual(agent.cmd_prune(self.journal.path), 0)
        self.assertEqual(self.journal.records(), [])
```

В `tests/test_folder.py` переименовать `test_version_is_3` в `test_version_is_4` с `self.assertEqual(agent.AGENT_VERSION, 4)`.

- [ ] **Step 2: Run tests to verify they fail**

Run: `/usr/bin/python3 -m unittest tests.test_runner tests.test_folder -v`
Expected: FAIL — `AttributeError: module 'agent' has no attribute 'cmd_prune'`; версия 3.

- [ ] **Step 3: Implement** — в `src/agent.py`: `AGENT_VERSION = 4`; после `cmd_run`:

```python
def cmd_prune(journal_path: str) -> int:
    """Удалить подтверждённые записи старше 30 дней. Под той же блокировкой, что run: prune перезаписывает файл, и запись,
    добавленная работающим агентом (finished — неотправленный отчёт), пропала бы (T2.3)."""
    lock = acquire_lock(journal_path)
    if lock is None:
        log("агент запущен с журналом %s — prune невозможен, сначала остановите агента" % journal_path)
        return 1
    try:
        removed = Journal(journal_path).prune(30)
        log("журнал: удалено записей %d" % removed)
        return 0
    finally:
        lock.close()
```

В `main` ветку `prune` заменить на `return cmd_prune(args.journal)`.

- [ ] **Step 4: Документы**
  - `.gitignore`: дописать `.wt/`.
  - `README.md`:
    - раздел про `prune` (около строки 121): «Не запускать при работающем агенте (ограничение 1 ниже).» →
      «При работающем агенте `prune` откажет («агент запущен…», код 1): сначала остановить агента.»;
    - ограничение 1 («`prune` не запускать при работающем агенте. Блокировки нет…») удалить, перенумеровать список;
    - ограничение «Сравнение описания в `ensure_fields` точное…» заменить на «**Сравнение текстов без различия
      переводов строк.** Описание и тело комментария сравниваются после замены `\r\n` на `\n` (Jira хранит правленное в
      UI с `\r\n`); отправляется текст команды как есть. Прочие различия (пробелы, завершающий перевод строки) — изменение.»;
    - «Версия»: «(сейчас 3)» → «(сейчас 4)»; добавить строку: «Версия 4 — сравнение текстов без различия `\r\n`/`\n`,
      полная пауза при времени журнала в будущем, `claim` без оценки из журнала, `prune` под блокировкой.»
  - `CLAUDE.md`: в «Команды» у `prune` «(не при работающем агенте)» → «(при работающем агенте откажет)».

- [ ] **Step 5: Run tests**

Run: `/usr/bin/python3 -W error::ResourceWarning -m unittest discover -s tests -t . && git status --short`
Expected: OK; `.wt/` не виден в `git status`.

- [ ] **Step 6: Commit**

```bash
git add src/agent.py tests/test_runner.py tests/test_folder.py README.md .gitignore CLAUDE.md
git commit -m "feat(agent): prune под блокировкой журнала, версия 4, README (#15)

T2.3 (agent#4).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>"
```