transcriber/openspec/specs/toolchain/spec.md

# toolchain Specification

## Purpose

Каким инструментом и какой его версии собирается сервис, и что об этом
проверяется до выкладки. Заведена задачей `go-1-26-upgrade` 2026-08-12 по
дефекту, записанному в `docs/review.md` за то же число: сборочный образ разошёлся
с требованием модуля, образ перестал собираться, а восемь шагов гейта и шесть
проходов ревью показали зелёное.

Capability нормирует **не поведение сервиса** для его потребителей, а поведение
инструмента разработки; потребитель у неё другой — тот, кто собирает сервис. Это
осознанное исключение, и оно названо в преамбуле `docs/architecture.md`.

## Requirements
### Requirement: Версия инструмента сборки объявлена одним числом

Проект SHALL объявлять версию Go, на которой собирается сервис, одинаково во
всех местах, где она названа. Мест ровно четыре, и перечень закрыт: требование
модуля в `go.mod`, сборочный образ в `Dockerfile`, строка стека в `CLAUDE.md`,
строка стека в `README.md`.

Сравниваются мажор и минор. Третье число у сборочного образа MUST оставаться
свободным, как и база образа: образ обновляется своим темпом, и требовать от
него совпадения по патчу значило бы краснеть на каждом его обновлении. Тег
читается по форме `golang:<мажор>.<минор>[.<патч>][-<база>]`, и берутся из него
первые два числа.

Правило множественности у мест разное, потому что места устроены по-разному.

**Документы** — `CLAUDE.md` и `README.md` — MUST называть версию ровно один раз,
и считается это **не по файлу, а по разделу стека**: `## Стек` в памятке,
`## Технологии` в README. Второе вхождение числа **в этом разделе** MUST
считаться отказом: обновят одно, второе протухнет молча. За пределами раздела
число не читается вовсе — иначе памятка, которая по устройству ведёт историю
закрытых долгов, роняла бы проверку на первой же правдивой строке о прошлой
версии, а сообщение толкало бы чинить не проверку, а исторический документ.

**Сборочный образ** единственности не требует: каждый слой — настоящий вход
сборки, и многослойная сборка законна. От всех вхождений `FROM golang:` MUST
требоваться совпадение мажора и минора, а не единственность.

**Требование модуля** называется директивой `go` и по устройству файла
единственно.

Граница раздела MUST быть определена, а не подразумеваться: раздел кончается
следующим заголовком того же или более высокого уровня, заголовок третьего уровня
и ниже остаётся внутри раздела, а строка, похожая на заголовок, но лежащая внутри
блока кода, заголовком MUST не считаться. Без этого пример в чужом разделе
открывал бы раздел стека на пустом месте, и число доставалось бы оттуда, откуда
норма его читать не велит.

`go.mod` MUST не содержать директиву `toolchain`. Она называет версию **пятым**
местом, которого перечень не знает: при `toolchain go1.27.0` четыре объявленных
числа сойдутся, а собирать будет пятое — то есть вернётся тот самый класс
расхождения, ради которого требование и заведено.

#### Scenario: Все четыре места названы одинаково

- **GIVEN** дерево проекта, где `go.mod`, `Dockerfile`, `CLAUDE.md` и `README.md`
  называют версию Go
- **WHEN** их читают подряд
- **THEN** мажор и минор совпадают во всех четырёх

#### Scenario: Патч сборочного образа отличается законно

- **GIVEN** `go.mod` требует `1.26.0`, а образ собирается на `golang:1.26.5-alpine`
- **WHEN** версии сравнивают
- **THEN** расхождением это не считается

#### Scenario: База сборочного образа сменилась

- **GIVEN** образ переехал с `golang:1.26-alpine` на `golang:1.26-bookworm`
- **WHEN** версии сравнивают
- **THEN** расхождением это не считается

#### Scenario: Раздел стека называет версию дважды

- **GIVEN** раздел стека в `CLAUDE.md` называет версию два раза
- **WHEN** версии сравнивают
- **THEN** это расхождение, даже если оба числа одинаковы

#### Scenario: Число за пределами раздела стека не читается

- **GIVEN** `CLAUDE.md` вне раздела стека упоминает прошлую версию Go — например
  записью о закрытом долге
- **WHEN** версии сравнивают
- **THEN** расхождением это не считается

#### Scenario: Сборочный образ собран в два слоя

- **GIVEN** `Dockerfile` содержит два `FROM golang:` с одним мажором и минором
- **WHEN** версии сравнивают
- **THEN** расхождением это не считается

#### Scenario: Слои сборочного образа разошлись между собой

- **GIVEN** `Dockerfile` содержит два `FROM golang:` с разными минорами
- **WHEN** версии сравнивают
- **THEN** это расхождение

#### Scenario: Заголовок раздела встретился внутри блока кода

- **GIVEN** документ в чужом разделе показывает пример, внутри которого есть
  строка, совпадающая с заголовком раздела стека, а ниже названо другое число
- **WHEN** версии сравнивают
- **THEN** число из примера не читается, и расхождением это не считается

#### Scenario: Раздел стека закрыт заголовком верхнего уровня

- **GIVEN** после раздела стека идёт заголовок первого уровня, а ниже названа
  прошлая версия
- **WHEN** версии сравнивают
- **THEN** это число не читается, и расхождением не считается

#### Scenario: Раздела стека нет вовсе

- **GIVEN** в документе нет раздела, где называется версия
- **WHEN** запускают шаг сверки
- **THEN** он завершается отказом и называет недостающий раздел

#### Scenario: Модуль объявляет версию пятым местом

- **GIVEN** `go.mod` содержит директиву `toolchain`
- **WHEN** версии сравнивают
- **THEN** это расхождение

### Requirement: Объявленное число — то, на котором проект собирается

Объявленная версия SHALL быть той, на которой сервис действительно собирается и
проходит тесты. Согласованность четырёх строк между собой этого не доказывает:
четыре одинаковых числа несуществующей версии требованию о согласованности
удовлетворяют, а собрать на них нельзя.

Проверка эта MUST оставаться за человеком и MUST не входить в набор проверок:
она требует сборки образа, а сборка образа набором проверок не делается
намеренно — дорого. Подъём версии MUST не уезжать в основную ветку, пока сборка
образа и тесты на объявленном числе не прогнаны.

#### Scenario: Версию подняли

- **GIVEN** объявленную версию Go подняли во всех четырёх местах
- **WHEN** изменение готовят к мерджу
- **THEN** до мерджа на этой версии прогнаны сборка образа и тесты

### Requirement: Расхождение версий роняет набор проверок

Набор проверок `task gate` SHALL включать шаг, который сравнивает объявленные
версии между собой и MUST завершаться отказом, когда они разошлись. Сообщение
отказа MUST называть **все четыре места и прочитанное в каждом число** — не одну
разошедшуюся пару: в дефекте 2026-08-12 три места из четырёх говорили одно и то
же и неверными были именно они, а по сообщению о паре человек чинит не то место.

Шаг MUST судить по содержимому файлов репозитория и MUST не спрашивать
установленный инструмент — ни `go version`, ни `go env`, ни `GOTOOLCHAIN`. Исход
его MUST быть функцией коммита, а не машины: шаг, чей ответ зависит от того, что
стоит на хосте, воспроизводит ровно ту подмену, которая держала дефект
2026-08-12 невидимым — там `go build ./...` шёл на хостовом Go, а объявленное
число не проверял никто.

Шаг MUST работать сравнением строк — без сборки образа, без docker и без сети —
и MUST не зависеть от рабочего каталога, из которого запущен. Шаг MUST только
читать: файлов он не правит и разошедшихся мест не чинит.

Коды выхода MUST следовать словарю прочих проверочных шагов проекта: 0 сошлось,
1 расхождение, 2 ошибка употребления, 3 окружение. Своего словаря шаг MUST не
заводить: раздел «Гейт» в `CLAUDE.md` объявляет словарь общим, и четвёртый шаг с
собственной семантикой сделал бы это утверждение неверным.

Место, где числа не нашлось вовсе, MUST считаться отказом с именем этого места.
«Нечего сравнивать» исходом MUST не быть: пропавшая строка иначе выглядела бы
как совпадение.

Отказ чтения места MUST не выглядеть как отсутствие числа. Место, которое
существует, но не читается, — это отказ окружения, и сообщение MUST говорить о
нечитаемости, а не о ненайденной версии: иначе шаг отправляет чинить документ, в
котором строка на месте, а сломаны права.

#### Scenario: Разошёлся сборочный образ

- **GIVEN** `Dockerfile` называет версию, отличную от прочих трёх мест
- **WHEN** запускают `task gate`
- **THEN** шаг сверки завершается отказом
- **AND** сообщение называет все четыре места и число каждого
- **AND** весь набор проверок краснеет

#### Scenario: Разошлось требование модуля

- **GIVEN** `go.mod` называет версию, отличную от прочих трёх мест
- **WHEN** запускают шаг сверки
- **THEN** он завершается отказом и называет `go.mod` среди разошедшихся

#### Scenario: Разошлась памятка

- **GIVEN** `CLAUDE.md` называет версию, отличную от прочих трёх мест
- **WHEN** запускают шаг сверки
- **THEN** он завершается отказом и называет `CLAUDE.md` среди разошедшихся

#### Scenario: Разошёлся README

- **GIVEN** `README.md` называет версию, отличную от прочих трёх мест
- **WHEN** запускают шаг сверки
- **THEN** он завершается отказом и называет `README.md` среди разошедшихся

#### Scenario: Версии совпадают

- **GIVEN** все четыре места называют одно число
- **WHEN** запускают `task gate`
- **THEN** шаг сверки проходит с кодом 0
- **AND** остальные шаги набора идут как прежде

#### Scenario: Инструмента сборки нет на машине

- **GIVEN** в `PATH` нет `go` вовсе
- **WHEN** запускают шаг сверки
- **THEN** исход и сообщение те же, что и при установленном `go`

#### Scenario: Ни docker, ни сети нет

- **GIVEN** docker недоступен и сети нет
- **WHEN** запускают шаг сверки
- **THEN** он отрабатывает и даёт тот же исход, что и при доступном docker

#### Scenario: Шаг запущен не из корня проекта

- **GIVEN** шаг запускают из подкаталога дерева
- **WHEN** он ищет свои четыре места
- **THEN** исход тот же, что и при запуске из корня

#### Scenario: Место существует, но не читается

- **GIVEN** файл одного из мест на диске есть, но прав на чтение нет
- **WHEN** запускают шаг сверки
- **THEN** он завершается кодом окружения и говорит о нечитаемости места
- **AND** сообщения «версия не названа» не печатает

#### Scenario: Версия не названа там, где должна быть

- **GIVEN** одно из четырёх мест перестало называть версию Go
- **WHEN** запускают шаг сверки
- **THEN** он завершается отказом и называет место, где число не нашлось