From fea0285619a2ab766e57443e0bdb3487210f1844 Mon Sep 17 00:00:00 2001 From: Anton Vakhrushev Date: Sun, 26 Jul 2026 12:55:16 +0300 Subject: [PATCH] =?UTF-8?q?todo:=20=D0=B7=D0=B0=D0=BA=D1=80=D1=8B=D1=82=20?= =?UTF-8?q?=D0=B2=D0=BE=D0=BF=D1=80=D0=BE=D1=81=20=D0=BF=D1=80=D0=BE=20?= =?UTF-8?q?=D0=BC=D0=BE=D0=B4=D0=B5=D0=BB=D1=8C=20=D1=81=D0=B1=D0=BE=D1=80?= =?UTF-8?q?=D0=BA=D0=B8,=20=D1=80=D0=B0=D0=B7=D0=BE=D0=B1=D1=80=D0=B0?= =?UTF-8?q?=D0=BD=D1=8B=20=D0=BF=D1=80=D0=BE=D1=82=D0=BE=D1=82=D0=B8=D0=BF?= =?UTF-8?q?=D1=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - вопрос 3 закрыт: модель записана в README и GUIDE, отмечены три места, где итог разошёлся с прежними заготовками — нет лока, нет маркеров секций, локальные префиксы не объявляются, а резервируются буквой `X` - вопрос 4 переформулирован: регионы не переносятся в единую секцию, а удаляются из канона — наполнять их в каноне нечем - вопрос 7 заменён разбором: транспорт переизобретался, оси и сборка аналога не имеют, Vale отклонён; в 1, 9 и 10 добавлены следствия --- TODO.md | 130 ++++++++++++++++++++++++++++++++------------------------ 1 file changed, 75 insertions(+), 55 deletions(-) diff --git a/TODO.md b/TODO.md index e4e1c65..39a0348 100644 --- a/TODO.md +++ b/TODO.md @@ -30,6 +30,13 @@ META-21 предлагает заменить путь на имя темы — где лежит полный документ. Самодостаточно и не тащит весь язык, но преамбула дублируется в каждом файле темы. +Появился четвёртый вариант, и он выглядит лучше трёх: **boilerplate-строка +как в RFC 8174**. Каждая конвенция несёт одну фразу — «ключевые слова … +толкуются как описано в „Языке конвенций“ версии 1 — тогда и только тогда, +когда написаны заглавными». Пути нет, документа рядом нет, а норму исполнить +можно: строка сама несёт и словарь, и правило капса. Разбирается в заходе +про язык записи, вместе с версией — она же цепляет вопрос 9. + Сопутствующее: `GUIDE.md` в телах конвенций не упоминается ни разу — проверено, так что вопрос только про `LANGUAGE.md`. @@ -63,46 +70,35 @@ META-21 предлагает заменить путь на имя темы — ссылках: это установка, а не целостность, но список подписок ему нужен из манифеста. -## 3. Согласованная модель сборки нигде не записана +## 3. Модель сборки — записана, закрыто -Самое срочное. Договорённости про плоскую раскладку живут только в -переписке, а репозиторий описывает прежнюю модель — и противоречит новой в -нескольких местах сразу. +Записана в `README.md` (разделы «Копия в репозитории» и «Манифест») и в +`GUIDE.md` (META-22, META-23). Плоская раскладка, файл на тему, один маркер +``, манифест из источника и списка тем, направление +строго одностороннее. -Что решено, но не зафиксировано: +Против прежних заготовок разошлось в трёх местах: -- копия плоская, файл на тему: `docs/conventions/config.md`, а не дерево - `arch/` + `lang/`; -- файл темы собирается из секций `arch → языки → стеки → local` с - машиночитаемыми маркерами `` и ``; -- языки и стеки образуют разреженную матрицу; файл темы собирает её строку, - многоязычная тема держит несколько языковых секций в одном файле; -- выбор описывается манифестом `.conventions.toml` в корне - репозитория-потребителя; путь к канону там **не** хранится; -- направление строго одностороннее: канон → код. Правка канона делается - руками в каноне, потом пересборка; -- локальные префиксы правил репозитория объявляются в манифесте и не - пересекаются с реестром канона. +- **лока нет** — «что было в прошлый раз» знает git, копии закоммичены, и + автоматического обновления не существует; заодно из шапки копии ушли + `origin_hash` и `synced`, осталось одно `origin:`; +- **маркеров секций нет** — раз обновление перезаписывает всё выше + локального маркера, разметка слоёв тулингу не нужна; слои идут обычными + заголовками; +- **локальные префиксы не объявляются в манифесте** — за репозиториями + зарезервирована буква `X`, столкновение невозможно по построению. -Что этому прямо противоречит в репозитории сейчас: +Остаётся переписать `conv`: сейчас в нём зеркальное дерево, именованные +регионы, `origin_hash` и команды `status`/`diff`/`push`. Это вопрос 2. -- `README.md` → «Раскладка в репозитории» показывает зеркальное дерево - `docs/conventions/arch/db-identifiers.md`; -- `README.md` → «Команды» и «Контракт с агентом» описывают `conv push` и - `conv push --new` как штатный путь; при односторонней модели транспорт - назад исчезает, остаётся только детект «копия правлена вне локальной - секции»; -- `conv` содержит `cmd_push` со всей обвязкой (`--new`, `--force`). +## 4. Именованные регионы — удалить из канона -## 4. Именованные регионы → одна локальная секция +Решение принято и записано: регионов нет, есть один маркер +``, который ставит сборщик в копии. Значит регионы не +переносятся в единую секцию, а **удаляются**: в каноне их нечем наполнять, +локальное принадлежит копии. -Решено заменить регионы `` на одну локальную секцию в -конце собранного файла: отступление ссылается на идентификатор правила -(`DIRS-5`), а не стоит рядом с ним. Это то, что делает -сравнение копии с каноном одним хешем и выкидывает из `conv` перенос -регионов по именам. - -Сделать перенос ещё предстоит: в каноне сейчас **31 регион в 12 файлах**. +Остаётся механическая работа — **31 регион в 12 файлах**: ``` 7 связано 7 отступления 7 механизировано @@ -110,9 +106,9 @@ META-21 предлагает заменить путь на имя темы — 1 проверки / поля / модель-владельца / маппинг / границы ``` -Отдельно решить, что делать с `связано`: сейчас это репо-специфичная часть -раздела «Связано» (META-17), и при единой локальной секции она переезжает -туда же — надо проверить, что META-17 после этого не противоречит сам себе. +Вопрос про `связано` снят: META-17 переписан, канонический раздел «Связано» +остаётся в тексте и содержит только ссылки, верные у всех, а репо-специфичные +уходят под маркер. ## 5. Пары слоёв и темы без базы @@ -144,27 +140,40 @@ META-21 предлагает заменить путь на имя темы — в закоммиченном файле не годится — репозиторий перестаёт быть самодостаточным и получает хардкод путей. Пересекается с вопросом 1. -## 7. Не переизобретено ли это +## 7. Не переизобретено ли это — разобрано -Проверить перед тем, как вкладываться в тулинг. Ближайшие кандидаты, куда -смотреть: +Проверка перед вложением в тулинг сделана. По слоям: -- **copier / cruft** — шаблон проекта с последующим `update`: ровно та же - задача «стянуть обновление апстрима, не затерев локальные правки», с - ответом через три-way merge вместо наших регионов. Стоит понять, почему у - них merge, а у нас исключение из сравнения. -- **vendir** — вендоринг чужого содержимого с лок-файлом; ближе к нашей - модели «канон это лавка». -- **Vale** — линтер прозы с правилами в файлах: значительная часть проверок - целостности канона (модальные слова вне правил, запрещённые формулировки) - выражается его языком. -- **RFC 2119 / 8174** — канонический источник модальных слов; наш словарь - фактически его перевод, полезно сверить границы значений. -- **EARS** — шаблоны требований (ubiquitous / event-driven / state-driven); - соседняя формализация того же, что мы решили таблицами. -- **Наборы правил для агентов** — `AGENTS.md`, cursor rules, скиллы: задачу - «раздать читаемые агентом договорённости по репозиториям» сейчас решают - несколько продуктов, и там уже могли устояться форматы. +- **Язык записи** — велосипед, но собранный из проверенных деталей: словарь + совпадает с RFC 2119/8174 вплоть до правила «нормативен только капс», + обязательное «Почему» — дисциплина из requirements engineering (ISO/IEC/IEEE + 29148), стабильные идентификаторы — из semgrep/ESLint. Менять архитектуру + нечего, остались шесть точечных дельт — отдельным заходом. +- **Оси и сборка** — аналога не нашлось. Ближайшие соседи (каскад `extends` + в ESLint, слои стилей Vale) дают праву слоя **отменять** базу; наш запрет + строже, и это содержательная часть. Вкладываться сюда. +- **Транспорт** — переизобретался, но задача у нас другая, чем у copier и + cruft. У них трёхсторонний merge потому, что шаблон порождает код, который + правят везде: расхождение неограниченно. У нас расхождение ограничено и + живёт под маркером, поэтому исключение из перезаписи лучше merge — + детерминированно и без конфликтных маркеров. Из vendir/cruft взят разбор + «манифест против лока», из ansible `blockinfile` — идея размечать + управляемый кусок, а не локальный. Лок при этом не взят: его роль играет + git. +- **Раздача агентам** — не наша задача, остаёмся на `AGENTS.md`/`CLAUDE.md` + плюс скиллы. + +**Vale отклонён.** Из восьми проверок в `LANGUAGE.md` он честно закрывает +две-три (модальные слова вне правил, запрещённые формулировки); остальные +пять структурные — «у каждого `### ПРЕФИКС-N` есть модальность и Почему», +«номера без дыр вниз», «префикс совпадает с реестром». Это разбор документа, +а не проверка токенов в области. Ради двух-трёх проверок тянуть ещё один +бинарь и директорию стилей при одном пользователе не стоит. + +**Что стоит посмотреть перед переписыванием `conv`** (вопрос 2): дистрибуцию +пакетов Vale (`.vale.ini` → `vale sync` → `styles/`) как готовый прототип +манифеста, и `vendir.yml` — как пример того, где проходит граница между +«чего хочу» и «что получил». ## 8. Мультиязычность ключевых слов @@ -198,6 +207,13 @@ MUST/SHOULD плотнее, чем на ДОЛЖЕН/СЛЕДУЕТ. Проти Цена — ещё одна сущность и ещё одна синхронизация. Проверить, не выйдет ли лечение хуже болезни при одном пользователе. +Оценка выросла: у выноса появилась вторая, независимая причина. Boilerplate- +строка из вопроса 1 обязана назвать язык **с версией** — иначе она врёт при +первом же изменении словаря. Версия предполагает документ, у которого версия +бывает, то есть отдельный от набора. Так IETF и решил ровно эту задачу: +RFC 2119 — самостоятельный документ, на который спецификации ссылаются +номером, а не путём. + ## 10. Тулинг на Go, живущий независимо Сейчас `conv` — питоновский скрипт внутри канона, то есть тулинг и данные в @@ -214,6 +230,10 @@ Go-бинарь со своим релизным циклом, ставить ч «целостность канона / установка в проект» дешевле заложить сразу, чем отпиливать потом. +Порядок при этом обратный написанному: пока вопрос 9 не сделан, инструмент +всё равно работает против одного конкретного канона, и независимый релизный +цикл ему нечего обслуживать. Сначала 9, потом 10. + ## 11. Ссылки на родительский слой своей темы Из `lang/` и `stack/` ссылаться на идентификаторы своего же арх-слоя