transcriber/openspec/changes/archive/2026-08-12-go-1-26-upgrade/design.md

## Context

Версия Go названа в проекте четырежды, и сегодня четыре места расходятся:
`go.mod` требует `go 1.25.0`, `Dockerfile` собирает на `golang:1.25-alpine`,
`CLAUDE.md` обещает «Go 1.25», а `README.md` не называет версию вовсе. На машине
разработки стоит `go1.26.5`.

Число 1.25 никем не назначалось: `go mod tidy` поднял требование модуля,
следуя за PocketBase, а образ подтянули следом. Ровно этот же механизм 2026-08-12
породил дефект — требование модуля уехало на 1.25, `Dockerfile` остался на
`golang:1.24-alpine` с `GOTOOLCHAIN=local`, и образ перестал собираться. Восемь
шагов набора проверок и шесть проходов ревью показали зелёное: `go build ./...`
идёт на хостовом Go, а образ не собирает ни один шаг. Случай записан в
`docs/review.md` за 2026-08-12 и там же назван способ починки — сравнение строк
вместо сборки образа.

Ограничения, в которых работаем: набор проверок обязан оставаться дешёвым и
работать без сети и без docker; выкладку это изменение не запускает; сборку
образа в набор проверок не заводим — отказ записан.

## Goals / Non-Goals

**Goals:**

- одно число версии Go во всех четырёх местах;
- шаг набора проверок, который краснеет на расхождении и называет оба числа;
- шаг стоит доли секунды и не зависит ни от docker, ни от сети.

**Non-Goals:**

- сборка образа шагом набора проверок — дорого, отказ записан в
  `docs/review.md`;
- проверка того, что объявленная версия вообще существует в реестре образов, —
  это требует сети;
- сверка версий прочих инструментов (`golangci-lint`, `task`, `ffmpeg`) — их
  расхождение так не ломает, и заводить перечень впрок незачем;
- `shellcheck` шагом набора проверок. Замер: shell-скриптов в гейте один, три
  соседних шага — Python в плагинах, линтер к ним неприменим; цена шага — одна
  строка плюс подавление ложного `SC1007` на идиому `CDPATH= cd`. Отказ всё равно
  осознанный, но цену называем настоящую, а не «их четыре»;
- автоматическая правка разошедшихся мест — шаг набора проверок судит, а не
  чинит.

## Decisions

### Решение 1: версия 1.26, а число выбирает человек

Берём 1.26 — она стоит на машине разработки (`go1.26.5`), образ
`golang:1.26-alpine` в реестре есть, последний релиз тоже `go1.26.5`, а
`CGO_ENABLED=0 go build ./...` на ней уже проходит. Требование PocketBase v0.39.10
(`go 1.25.0`) она выполняет.

В `go.mod` пишем `go 1.26.0`, а не `1.26.5`: требование модуля — это нижняя
граница, и привязывать её к патчу значит без нужды отсекать сборку на более
раннем патче той же минорной версии.

**Число называет человек, и нормой это не записано намеренно.** `go mod tidy`
поднимает требование модуля сам, следуя за зависимостью, и подъём, никем не
назначенный, дал сегодняшнее расхождение. Но «выбрал человек» ненаблюдаемо:
директива, поднятая инструментом, и директива, назначенная решением, выглядят
одинаково, а норма, которую нечем уронить, расходится с кодом молча. Поэтому
здесь мотив, а в спеке — то, что проверяется: сборка и тесты на объявленном
числе до мерджа.

**Отвергнуто: остаться на 1.25 и завести только сверку.** Сверка — половина
задачи, и она бы прижилась; но тогда сегодняшнее число остаётся тем, которое
никто не назначал, и первый же `go mod tidy` следующей зависимости повторит
подъём вслепую. Задача собрана из двух половин именно поэтому.

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

### Решение 2: новая capability `toolchain`

Дельта-спека ложится в новую capability `toolchain` — «каким инструментом и какой
его версии собирается сервис, и что об этом проверяется до выкладки».

**Отвергнуто: дописать в `pipeline`.** `pipeline` нормирует прогон воркера и
захват задачи — поведение работающего сервиса. Версия сборщика с ним не меняется
вместе, а правило гранулярности в `openspec/config.yaml` именно про это: «дробить,
когда в одной спеке смешиваются разные заботы».

**Отвергнуто: обойтись без дельта-спеки.** Изменение вводит проверяемое
требование — «расхождение роняет набор проверок», — и требование без дома
проверяется только памятью того, кто его завёл. Обещание «образ собирается» уже
один раз жило в трёх документах и во всех трёх было неверным.

**Отвергнуто имя `build`.** Первая редакция называла capability `build`, и на
разметке выяснилось, что читать её нельзя: настройка среды разработчика
запрещает чтение любого каталога с этим именем. Спека, недоступная проходам
ревью, не проверяется ни одним из них, а после архивации осталась бы слепым
пятном насовсем. Имя `toolchain` точнее и по существу: предмет здесь —
инструмент сборки и его версия, а не сборка как процесс.

Признаём натяжение: три существующие capability описывают поведение сервиса для
его потребителей, а `toolchain` описывает поведение инструмента разработки.
Потребитель у него другой — тот, кто собирает сервис. Правило `config.yaml`
говорит «поведение **или домен** системы»; инструмент сборки — домен, и именно
как домен он здесь и назван. Если capability так и останется с одним
требованием, дешевле будет переименовать её, чем расщепить
(`RENAMED Requirements`).

### Решение 3: шаг сверяет все четыре места, а не два

Минимум по критерию приёмки — `go.mod` против `Dockerfile`. Берём шире: плюс
`CLAUDE.md` и `README.md`.

Причина прямо из дефекта 2026-08-12: **три места из четырёх говорили одно и то
же, и неверными были именно они.** Пару `go.mod`↔`Dockerfile` парная сверка
тогда поймала бы — та пара как раз разошлась. Чего она не ловит, так это
документа, разошедшегося с **согласованным** кодом: сойдись тогда `go.mod` с
образом на 1.24, и памятка с README продолжали бы врать молча, а гейт оставался
бы зелёным. Сегодня проект ровно в этом состоянии наполовину: `README.md` не
называет версию вовсе, а `CLAUDE.md` проверяется только тем, что кто-то её
прочтёт.

Цена: строку о версии придётся держать в форме, которую находит машина. Это же и
польза — документ, чья строка перестала находиться, краснеет вместо того, чтобы
молча протухнуть.

**Отвергнуто: сверять только `go.mod` и `Dockerfile`.** Дешевле на три строки
скрипта и не ловит половину прошлого дефекта.

**Отвергнуто: сверять ещё и `config.dist.toml`, `docker/entrypoint.sh` и
Ansible-роль в `pet-project-server`.** Версии Go там нет; чужой репозиторий этому
набору проверок недоступен.

### Решение 4: отдельный скрипт в репозитории, а не строка в `Taskfile.yml`

Шаг живёт файлом `scripts/check-go-version.sh`, а `Taskfile.yml` его зовёт.

Сверка четырёх мест — это четыре разных способа достать число (директива
модуля, тег образа, проза памятки, проза README), сравнение и внятное сообщение
со всеми четырьмя. В `Taskfile.yml` это легло бы двадцатью строками shell внутри
YAML, где их не читает ни редактор, ни `shellcheck`, а кавычки экранируются
дважды. Соседние шаги (`docs`, `tasks`, `openspec`) уже зовут скрипты, и эта
форма для набора проверок родная.

Скрипт лежит в репозитории, а не в плагине: он про этот проект, а не про метод
работы.

Оговорка о выигрыше: `shellcheck` шагом набора проверок этим изменением **не**
заводится, и обоснование выше стоит на том, что файл хотя бы **можно** проверить
и прочитать глазами, а не на том, что его кто-то проверяет машиной. Заводить
линтер оболочки — отдельная работа, и она уезжает урожаем.

**Отвергнуто: строка shell прямо в `Taskfile.yml`.** Дешевле на один файл,
дороже при первом же изменении: правка регулярного выражения в YAML-скаляре
ошибается молча.

**Отвергнуто: написать проверку на Go отдельной командой.** Тогда она попадает в
`go build ./...` и `go vet ./...`, а вместе с ней — разбор `Dockerfile` в коде
сервиса. Проверка о проекте не должна ехать в бинарник сервиса.

### Решение 5: форма строки, которую ищет машина

| Место | Что ищем | Правило множественности |
| --- | --- | --- |
| `go.mod` | единственная строка, начинающаяся с `go ` — первые два числа | директива `toolchain` запрещена: она пятое место |
| `Dockerfile` | тег `golang:<мажор>.<минор>[.<патч>][-<база>]`, берём первые два числа | все вхождения `FROM golang:` обязаны давать одно число |
| `CLAUDE.md` | образец `Go <мажор>.<минор>` в разделе `## Стек` | ровно одно вхождение в разделе; вне раздела число не читается |
| `README.md` | образец `Go <мажор>.<минор>` в разделе `## Технологии` | ровно одно вхождение в разделе; вне раздела число не читается |

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

Правило множественности заведено не впрок: реализация, молча берущая первое
совпадение, судила бы по обновлённой строке и не видела протухшей соседней.

**Рамка у него — раздел, а не файл, и это правка по находке ревью.** Первая
редакция считала вхождения по всему файлу, и на памятке это давало
гарантированный ложный красный: она по устройству ведёт историю закрытых долгов
(«Два прежних долга закрыты и здесь названы»), и первая же правдивая строка о
прошлой версии уронила бы шаг — сообщением, которое толкает чинить не шаг, а
исторический документ. Тем же ловился бы любой пример команды в README. Решение
человека на чекпоинте: считать по разделу стека, за его пределами число не
читать.

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

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

### Решение 6: шаг судит по репозиторию, а не по машине

Число берётся чтением файлов. `go` шаг не зовёт вовсе — ни `go mod edit -json`,
ни `go list -m`, ни `go env`.

Способ это не самый удобный: разбор директивы через `go mod edit -json` короче и
надёжнее регулярного выражения. Он же и опасный: вызов `go` тянет за собой
`GOTOOLCHAIN`, `$PATH` и установленный тулчейн, а при непустом `GOTOOLCHAIN` `go`
вправе полезть в сеть за нужной версией — то есть требование «без сети»
перестало бы выполняться. Хуже того, исход шага стал бы зависеть от машины, а не
от коммита, — ровно та подмена, которая держала дефект 2026-08-12 невидимым:
`go build ./...` шёл на хостовом Go и потому был зелёным, пока образ не
собирался.

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

Оболочка — POSIX `sh`, без GNU-only флагов (`grep -P`, `sed -E` с
расширениями, `mapfile`). Пути шаг строит от корня репозитория, а не от текущего
каталога: иначе его исход зависел бы от того, откуда он запущен.

## Risks / Trade-offs

- **Скрипт ищет число прозой документа, и переписанная строка сломает шаг** →
  сообщение отказа называет место, где число не нашлось, поэтому чинится
  однозначно и сразу. Ложное зелёное здесь невозможно по построению: не нашлось
  — отказ.
- **Четыре места вместо двух — четыре места, которые надо править при подъёме
  версии** → это цена решения 3, и она осознанная: молчаливо врущий документ
  дороже одной лишней правки.
- **1.26 может оказаться несовместимой с зависимостью, которую мы ещё не
  трогали** → проверяется до мерджа: `task image` собирает образ на объявленной
  версии, а `go test ./...` идёт на хостовом go1.26.5. Обе проверки в критериях
  приёмки.
- **Шаг проверяет согласованность чисел, но не то, что образ собирается** →
  осознанный остаток. Собранный образ по-прежнему видит только тот, кто позвал
  `task image` руками; сверка ловит класс расхождений, а не все отказы сборки.