Постановка задачи: task contract

Спецификация дневника описывает поведение нескольких функций. Одному запуску агента обычно достаётся только часть работы. Например, нужно добавить проверку диапазона балла, сохранив формат записи и не меняя отчёт. Task contract фиксирует именно эту порцию работы: цель, разрешённые изменения, проверки и причины остановиться.

Ограничим задачу

Просьба «улучши валидацию дневника» оставляет открытыми и проблему, и критерии приёмки. Более определённая постановка для учебного проекта могла бы выглядеть так:

Функция validate_pain_entry принимает True как оценку боли, потому что в Python bool является подклассом int. Нужно отклонять логические значения с ValidationError, сохранив приём целых чисел от 0 до 10. Можно изменить проверку типа и добавить тесты. Формат PainEntry, нормализацию текста и отчёт не менять. После изменения должны проходить новые тесты на True и False, проверки границ 0 и 10 и существующий набор тестов.

Эта задача взята из поведения текущего учебного кода. Она достаточно мала, чтобы проверить весь diff за одно ревью. Из неё понятно и то, почему не стоит заодно переписывать нормализацию заметок.

Какие поля нужны

Поле	Что написать для этого исправления
Цель	Логические значения больше не принимаются как балл.
Основание	Ссылка на спецификацию и пример validate_pain_entry(True).
Область изменения	Проверка типа в algi/domain.py, тесты в tests/.
Что оставить без изменений	Формат записи, нормализацию текста, отчёт.
Приёмка	True и False отклоняются; 0 и 10 принимаются.
Проверки	python3 -m unittest discover -s tests.
Остановка	Если исправление требует менять публичный формат записи, сначала согласовать задачу.

Для короткого исправления эти сведения поместятся в обычный issue. Полный шаблон нужен, когда ограничений больше; пустые разделы можно удалить.

Что runner читает из JSON

В стенде задачи лежат в examples/harness-labs/tasks/. Фрагмент первой задачи ALGI:

{
  "id": "algi-01-pain-diary",
  "spec": "specs/pain-diary.bdd.md",
  "context": ["AGENTS.md", "specs/pain-diary.bdd.md"],
  "scripted_fixture": "../fixtures/algi-pain-diary",
  "checks": [
    {
      "name": "unit tests",
      "command": ["python3", "-m", "unittest", "discover", "-s", "tests"]
    }
  ]
}

Это выдержка, а не полный файл для запуска. Runner проверяет наличие spec и файлов context в рабочей папке, применяет scripted_fixture, затем выполняет команды из checks. Путь к fixture отсчитывается от папки файла задачи, остальные перечисленные здесь пути - от рабочей папки проекта.

Поля acceptance_criteria и expected_outputs тоже есть в полном JSON, но учебные версии runner их не проверяют. Содержимое спецификации они не интерпретируют: проверяется существование файла. Поэтому запись требования в JSON сама по себе не превращает его в автоматическое условие приёмки.

Это место для доработки harness. Например, проверку наличия ожидаемых файлов можно выполнить кодом; требование «отчёт понятен врачу» придётся разложить на более конкретные проверки и ревью.

Заранее решите, что будет при отказе

Если нужного файла контекста нет, продолжать работу с догадками не стоит: в v02 и v03 запуск получает blocked. Если тест выполнился и завершился ошибкой, результат будет failed. В обоих случаях полезно знать следующий шаг: восстановить файл, исправить реализацию или уточнить требование.

Для задачи, затрагивающей данные пациентов, потребуется ревью даже после зелёных тестов. В учебном runner отдельного статуса needs_review ещё нет; его нельзя получить, просто добавив такую фразу в задачу. Пока это правило ручной приёмки. Позже его можно сделать отдельным условием runner.

Проверка постановки

Передайте задачу коллеге без дополнительных пояснений. Попросите назвать допустимые изменения и один результат, который он отклонит. Если для ответа приходится пересказывать старый чат, добавьте недостающие сведения в задачу или в документ, на который она ссылается.

Постоянные правила проекта при этом не нужно копировать в каждый issue. В следующей главе разберём, где их хранить и как разрешать противоречия.