оси: перечень получил дом, две бездомные оси переехали в shared
Слияние ничего из идей не тронуло, но сделало дешёвым дом для правила, натянутого между скиллами. Заведён shared/axes.md — дом перечня, а не значений: девять осей, их адреса и чего каждая не решает. Механика остаётся у владельца. Целиком сюда переехали две оси, у которых владельца не было. Коды выхода объявлялись общим словарём в одиннадцати местах, и каждое объявление называло свой набор соседей; машина их не сверяла, потому что copies.py смотрит markdown, а перечни лежали в docstring'ах. Теперь дом один, скрипты держат указатель, а три SKILL.md — помеченную копию, потому что на кодах они ветвятся. Режим прогона (с меткой, без метки) был размазан по четырём файлам и осью назван не был, хотя в уставе review-basics задаёт саму возможность запуска. Разведены два значения слова «стадия»: ступени 1-5 внутри прогона кода, стадии дизайна и кода снаружи. Карта нашла ошибку в себе: клетка «категория документа × метка» пустой не была — review-basics приёмник проектных тем при любой метке. Пустой оказалась соседняя: на прогоне без метки план фиксирован, и своих тем проекта в нём нет вовсе. Обе оставшиеся пустоты названы вслух, а не заполнены наугад.
This commit is contained in:
@@ -74,10 +74,30 @@ python3 $os check --dir <корень> # форма config.yaml в проек
|
||||
python3 $os form # слепок формы против живого OpenSpec
|
||||
```
|
||||
|
||||
**Коды выхода — общий словарь скриптов av-dev:** 0 сошлось, 1 дрейф, 2 ошибка
|
||||
употребления, 3 окружение, 4 внутренний сбой. Ветвись на коде, а не на тексте.
|
||||
Различать 1 и 3 обязательно: «форма разошлась» — рабочая ситуация, «openspec не
|
||||
отвечает» — нерабочая.
|
||||
**Копия.** Дом словаря — `shared/axes.md` в репозитории плагина: словарь общий
|
||||
для всех скриптов, и ни один скилл им не владеет. Правится дом, а не этот файл.
|
||||
|
||||
<!-- копия: коды-выхода из av-dev/shared/axes.md -->
|
||||
|
||||
**Коды выхода — общий словарь всех скриптов `av-dev`. Ветвись на коде, а не на
|
||||
тексте вывода.**
|
||||
|
||||
| Код | Что случилось |
|
||||
| --- | --- |
|
||||
| 0 | сошлось |
|
||||
| 1 | дрейф: рабочая ситуация, чинится |
|
||||
| 2 | ошибка употребления: аргументы или нарушенное правило |
|
||||
| 3 | окружение: не тот каталог, битый конфиг, нет инструмента |
|
||||
| 4 | внутренний сбой — дефект скрипта, доложить |
|
||||
|
||||
**Различать 1 и 3 обязательно.** «Дрейф» — рабочая ситуация, и чинится она
|
||||
правкой предмета; «окружение» — нерабочая, и повтор той же командой не поможет.
|
||||
Одинаковая реакция на них неверна в обоих случаях.
|
||||
|
||||
<!-- /копия: коды-выхода -->
|
||||
|
||||
Здесь это значит: «форма разошлась» — рабочая ситуация, «openspec не отвечает» —
|
||||
нерабочая.
|
||||
|
||||
`check` проверяет форму, и каждая проверка — про молчащий пробел, а не про вкус:
|
||||
каталог есть; имя именно `config.yaml` (`config.yml` OpenSpec не читает и об этом
|
||||
|
||||
@@ -16,12 +16,8 @@
|
||||
PyYAML в стандартной библиотеке нет. Всё проверяемое различимо построчно,
|
||||
комментарии отброшены, ключи верхнего уровня стоят в первой колонке.
|
||||
|
||||
Коды выхода — общий словарь скриптов av-dev:
|
||||
0 сошлось
|
||||
1 дрейф: форма разошлась с ожидаемой
|
||||
2 ошибка употребления: аргументы
|
||||
3 окружение: не тот каталог, инструмент не отвечает
|
||||
4 внутренний сбой
|
||||
Коды выхода — общий словарь скриптов av-dev; дом словаря и разбор «дрейф
|
||||
против окружения» — av-dev/shared/axes.md. Значения — в константах ниже.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
@@ -126,6 +126,9 @@ description: "Взять одну задачу и довести её до за
|
||||
|
||||
## Развилка: какой сценарий
|
||||
|
||||
Сценарий — ось процесса; перечень осей и их границ —
|
||||
[shared/axes.md](../../shared/axes.md).
|
||||
|
||||
Она в два вопроса, и оба стоят до всякой работы.
|
||||
|
||||
**Первый: есть ли у задачи один очевидный способ решения?**
|
||||
|
||||
@@ -313,6 +313,11 @@ charter'а, а модель потом двигает калибровка, и
|
||||
|
||||
## Метки
|
||||
|
||||
**«Стадия» и «ступень» — разные членения, и путать их нельзя.** Стадий ревью
|
||||
две — дизайна и кода, — и они видны снаружи: их зовёт `av-dev:code-resolve` в
|
||||
разных точках цикла. Ступеней внутри прогона кода пять, они нумерованы и наружу
|
||||
не выходят. Перечень осей процесса целиком — [shared/axes.md](../../shared/axes.md).
|
||||
|
||||
**Классификация задачи выдаёт ровно одно значение — метку**: `small`, `medium`
|
||||
или `large`. Это **единственный вход, по которому конвейер выбирает
|
||||
исполнителей**: и на дизайне, и на коде состав читается из неё, а не из класса
|
||||
@@ -402,7 +407,7 @@ flowchart TD
|
||||
|
||||
Отсюда состав обеих стадий:
|
||||
|
||||
| Метка | Когда | Ревью дизайна | Ревью кода: стадии | Проходов всего | Доля задач |
|
||||
| Метка | Когда | Ревью дизайна | Ревью кода: ступени | Проходов всего | Доля задач |
|
||||
|---|---|---|---|---|---|
|
||||
| `small` | малое **и** знакомое: багфикс, локальная правка, доки | `specs` | 1, 2, 5 (+3 при своих темах) | **5–6** | **до трети, и меньше, чем `medium`** |
|
||||
| `medium` | **рабочее умолчание**: среднее и знакомое | `specs`, `rubric` | 1, 2, 3, 5 | **7** | **большинство** |
|
||||
@@ -463,7 +468,7 @@ flowchart TD
|
||||
```mermaid
|
||||
flowchart TD
|
||||
plan[/"план разметки задачи<br/>(готов до ревью кода)"/]
|
||||
autotests["autotests<br/>(стадия 1, держит машину)"]
|
||||
autotests["autotests<br/>(ступень 1, держит машину)"]
|
||||
specs["specs"]
|
||||
code["code"]
|
||||
basics["basics<br/>(medium: темы ядра и свои;<br/>small, large: только свои темы проекта)"]
|
||||
@@ -513,7 +518,7 @@ flowchart TD
|
||||
|
||||
Ресурс один и неделимый: **машина** — тесты, поднятый сервис, СУБД, порты, диск.
|
||||
Проходы, заявившие его, сериализуются между собой при любой метке и на любой
|
||||
стадии; порядок внутри цепочки произволен.
|
||||
ступени; порядок внутри цепочки произволен.
|
||||
|
||||
| Проход | Держит машину | Почему |
|
||||
|---|---|---|
|
||||
@@ -653,6 +658,30 @@ flowchart TD
|
||||
(тулчейн и сборка, зависимости, гит-хуки, перенос, чистка). Он приходит **без
|
||||
change**: у работы, не меняющей поведения, дельта-спек нет по построению.
|
||||
|
||||
**Копия.** Дом оси — `shared/axes.md` в репозитории плагина: режим делят конвейер,
|
||||
сценарий обслуживания и два устава, и ни один из них им не владеет. Правится дом,
|
||||
а не этот файл.
|
||||
|
||||
<!-- копия: режим-прогона из av-dev/shared/axes.md -->
|
||||
|
||||
**Прогон ревью идёт в одном из двух режимов, и режим — не глубина.**
|
||||
|
||||
- **С меткой** — обычный прогон по change: разметку сделал `review-scope`, состав
|
||||
обеих стадий выведен из метки.
|
||||
- **Без метки** — прогон сценария обслуживания: change нет, размечать нечего,
|
||||
план фиксирован и назван сценарием. Разметчик не запускается вовсе.
|
||||
|
||||
**Без метки — не то же самое, что `small`.** `small` — это суждение о размере и
|
||||
сложности, снятое с изменения; отсутствие метки — утверждение, что снимать её
|
||||
не с чего. Проход, подставивший себе `small` там, где метки нет, вывел бы
|
||||
глубину из ничего.
|
||||
|
||||
**Режим правит не только состав, но и саму возможность запуска.** Проход, у
|
||||
которого запуск задан меткой, без метки не имеет ответа на вопрос «запускаться
|
||||
ли» — и ответ ему даёт план сценария, а не умолчание.
|
||||
|
||||
<!-- /копия: режим-прогона -->
|
||||
|
||||
**Метка на таком прогоне не назначается, и разметчик не зовётся.** Обе его оси
|
||||
здесь не определены: размер он выводит из `proposal.md`, `design.md`, `tasks.md`
|
||||
и дельта-спек, а сложность — из формы решения, которая у обслуживания либо
|
||||
@@ -687,7 +716,7 @@ change**: у работы, не меняющей поведения, дельт
|
||||
проект семантикой гейта в `CLAUDE.md`; не объявил — это строка границ покрытия, а
|
||||
не догадка прохода.
|
||||
|
||||
## Стадия 1 — Автотесты (обязательна при любой метке)
|
||||
## Ступень 1 — Автотесты (обязательна при любой метке)
|
||||
|
||||
Агент `review-autotests`, тема `autotests`. Запускает команду гейта из семантики
|
||||
гейта в `CLAUDE.md` и интерпретирует вывод.
|
||||
@@ -714,7 +743,7 @@ change**: у работы, не меняющей поведения, дельт
|
||||
Шаги, которые красят гейт безусловно, перечислены в `CLAUDE.md` с причиной. Проходу
|
||||
запрещено списывать такой отказ в мелочь.
|
||||
|
||||
## Стадия 2 — Сверка (обязательна при любой метке)
|
||||
## Ступень 2 — Сверка (обязательна при любой метке)
|
||||
|
||||
Два прохода, оба против **записанного** критерия. Машину не держат ни один, ребра
|
||||
между ними нет — уходят одним сообщением сразу после зелёного гейта, вместе со
|
||||
@@ -728,7 +757,7 @@ change**: у работы, не меняющей поведения, дельт
|
||||
обычном входе: необработанная ветка отказа, пустое значение, граница диапазона,
|
||||
перепутанный операнд, неосвобождённый ресурс, неверно применённый интерфейс
|
||||
библиотеки. Вторая сверяет с конвенциями проекта, беря только ту их часть,
|
||||
которая **не выражается правилом**: механизируемое уже проверила стадия 1.
|
||||
которая **не выражается правилом**: механизируемое уже проверила ступень 1.
|
||||
**На `small` у него есть третья, узкая обязанность** — сверить дифф с
|
||||
записанными инвариантами `CLAUDE.md` по темам `security`, `operations` и
|
||||
`architecture`, потому что с этой меткой `basics` не идёт. Потолок 1 находка
|
||||
@@ -756,7 +785,7 @@ change**: у работы, не меняющей поведения, дельт
|
||||
недосмотренной темы.
|
||||
|
||||
Recall темы `conventions` равен длине конвенций проекта — это предел любой
|
||||
сверки, и ровно ради него существуют стадии 3 и 4.
|
||||
сверки, и ровно ради него существуют ступени 3 и 4.
|
||||
|
||||
**Оба прохода на верхней модели, и по одной причине — цене пропуска.** У `specs`
|
||||
это направление `code → spec`: надо заметить **отсутствие** — тихий фолбэк,
|
||||
@@ -765,7 +794,7 @@ Recall темы `conventions` равен длине конвенций прое
|
||||
границах покрытия; прочие проходы с мнением держат `opus` из-за цены **ложных**
|
||||
находок, эти двое — из-за цены пропущенных.
|
||||
|
||||
## Стадия 3 — Темы (`medium` целиком; `small` и `large` — только свои темы проекта)
|
||||
## Ступень 3 — Темы (`medium` целиком; `small` и `large` — только свои темы проекта)
|
||||
|
||||
Агент `review-basics`. Один проход, машину не держит, ничего не запускает и не
|
||||
меряет — уходит одним сообщением вместе со стадией 2, сразу после зелёного гейта.
|
||||
@@ -802,7 +831,7 @@ Recall темы `conventions` равен длине конвенций прое
|
||||
взгляда на ось времени — значит изменение, которое не откатывается обратной
|
||||
правкой, на `small` не идёт вовсе, каким бы малым оно ни было.
|
||||
|
||||
## Стадия 4 — Доказательство (только `large`)
|
||||
## Ступень 4 — Доказательство (только `large`)
|
||||
|
||||
Три прохода, и все три уходят сразу после зелёного гейта, в одном ряду со
|
||||
стадией 2. Каждый берёт свою тему и доводит её до **доказательства**:
|
||||
@@ -831,7 +860,7 @@ Recall темы `conventions` равен длине конвенций прое
|
||||
ось времени и эксплуатации. Ровно поэтому они и стоят денег: оракул добывается
|
||||
запуском, а запуск — это машина, цепочка и часы.
|
||||
|
||||
Раньше эта пара стояла в `medium`, то есть на большинстве задач. Стадия
|
||||
Раньше эта пара стояла в `medium`, то есть на большинстве задач. Ступень
|
||||
переехала в `large` **сознательно и по цене, а не потому, что перестала находить**:
|
||||
она осталась самой ценной, но её ценность оплачивается на каждой задаче, а
|
||||
получается — на немногих. Что из-за этого перестало проверяться на младших метках, названо в «Честном пределе» и обязано идти строкой в границы покрытия
|
||||
@@ -849,7 +878,7 @@ Recall темы `conventions` равен длине конвенций прое
|
||||
записки; для архитектурного — что граница домена берётся из `passport.*`, а не из
|
||||
истории решений. Обе потери названы в «Честном пределе».
|
||||
|
||||
**Условие стадии и есть условие метки `large`:** изменение крупное **или**
|
||||
**Условие ступени и есть условие метки `large`:** изменение крупное **или**
|
||||
незнакомое — любая из двух осей. Разведены они не для красоты: у архитектурного
|
||||
прохода работа появляется от **размера** (трогается несколько слоёв разом или в
|
||||
проекте становится больше сущностей, чем было), у меряющей пары — от
|
||||
@@ -870,7 +899,7 @@ Recall темы `conventions` равен длине конвенций прое
|
||||
конфигурируемость, подстраховка поверх подстраховки. Потолок — 3 находки плюс
|
||||
секция «дешевле переделать до мерджа».
|
||||
|
||||
## Стадия 5 — Triage (обязательна)
|
||||
## Ступень 5 — Triage (обязательна)
|
||||
|
||||
Агент `review-triage`. **Единственный сток графа и единственный, кто агрегирует.**
|
||||
Входящие рёбра — все запущенные проходы: пока хоть один не вернул отчёт, триаж не
|
||||
|
||||
@@ -43,6 +43,8 @@
|
||||
|
||||
## Шкала severity
|
||||
|
||||
Severity — ось процесса; перечень осей — [shared/axes.md](../../../shared/axes.md).
|
||||
|
||||
| Severity | Что это | Пример |
|
||||
|---|---|---|
|
||||
| `critical` | нарушение инварианта проекта, потеря или порча данных, утечка секрета, построенный путь к отказу | запись потеряна при слиянии; тело пользовательской выгрузки в поле лога |
|
||||
|
||||
@@ -58,11 +58,30 @@ python3 $ds bump --dir <корень> # поднять вер
|
||||
не проверяет никто, и это надо сказать строкой доклада, а не считать, что она
|
||||
верна.
|
||||
|
||||
**Коды выхода — тот же словарь, что у `tasks.py`:** 0 сошлось, 1 дрейф, 2 ошибка
|
||||
употребления, 3 окружение, 4 внутренний сбой. Ветвись на коде, а не на тексте.
|
||||
**Копия.** Дом словаря — `shared/axes.md` в репозитории плагина: словарь общий
|
||||
для всех скриптов, и ни один скилл им не владеет. Правится дом, а не этот файл.
|
||||
|
||||
Различать 1 и 3 обязательно: «дрейф раскладки» — рабочая ситуация, «это не
|
||||
корень проекта» — нерабочая.
|
||||
<!-- копия: коды-выхода из av-dev/shared/axes.md -->
|
||||
|
||||
**Коды выхода — общий словарь всех скриптов `av-dev`. Ветвись на коде, а не на
|
||||
тексте вывода.**
|
||||
|
||||
| Код | Что случилось |
|
||||
| --- | --- |
|
||||
| 0 | сошлось |
|
||||
| 1 | дрейф: рабочая ситуация, чинится |
|
||||
| 2 | ошибка употребления: аргументы или нарушенное правило |
|
||||
| 3 | окружение: не тот каталог, битый конфиг, нет инструмента |
|
||||
| 4 | внутренний сбой — дефект скрипта, доложить |
|
||||
|
||||
**Различать 1 и 3 обязательно.** «Дрейф» — рабочая ситуация, и чинится она
|
||||
правкой предмета; «окружение» — нерабочая, и повтор той же командой не поможет.
|
||||
Одинаковая реакция на них неверна в обоих случаях.
|
||||
|
||||
<!-- /копия: коды-выхода -->
|
||||
|
||||
Здесь это значит: «дрейф раскладки» — рабочая ситуация, «это не корень проекта» —
|
||||
нерабочая.
|
||||
|
||||
### Граница механизируемого — объявляется вслух
|
||||
|
||||
|
||||
@@ -71,6 +71,9 @@ openspec/
|
||||
|
||||
## Три категории документов
|
||||
|
||||
Категория документа — ось процесса; перечень осей и того, чего каждая **не**
|
||||
решает, — [shared/axes.md](../../../shared/axes.md).
|
||||
|
||||
Раньше здесь стояло плоское правило «каждый документ `docs/` — тема ревью». Оно
|
||||
неверно ровно наполовину: паспорт и схема хранилища ревью нужны, но темами не
|
||||
являются, а журнал решений и журнал наблюдений ревью изменения не нужны вовсе.
|
||||
|
||||
@@ -6,12 +6,8 @@
|
||||
маркеры долга и две сверки с кодом. Смысловые дубли и оставшееся в архитектуре
|
||||
поведение судит агент — скрипт об этом говорит вслух в конце отчёта.
|
||||
|
||||
Коды выхода — тот же словарь, что у tasks.py:
|
||||
0 сошлось
|
||||
1 дрейф раскладки (рабочая ситуация, чинится)
|
||||
2 ошибка употребления
|
||||
3 окружение: не тот каталог, битый конфиг
|
||||
4 внутренний сбой
|
||||
Коды выхода — общий словарь скриптов av-dev; дом словаря и разбор «дрейф
|
||||
против окружения» — av-dev/shared/axes.md. Значения — в константах ниже.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
@@ -256,7 +256,9 @@ stateDiagram-v2
|
||||
|
||||
## Тип записи
|
||||
|
||||
**Тип — единственная ось, и он решает, что с записью можно делать.** Дом типа —
|
||||
**Тип — единственная ось этого скилла, и он решает, что с записью можно делать.**
|
||||
Перечень осей всего процесса и того, чего каждая **не** решает, —
|
||||
[shared/axes.md](../../shared/axes.md). Дом типа —
|
||||
**поле меты `Тип` первой строкой**; эмодзи в заголовке H1 от него производна, её
|
||||
ставит `add` и чинит `check --fix`.
|
||||
|
||||
@@ -398,18 +400,31 @@ python3 $tk init --dir D [--sections …] [--items …] [--backlog …] …
|
||||
python3 $tk adopt scan --from … | apply --plan … # разовая адаптация, references/adopt.md
|
||||
```
|
||||
|
||||
**Коды выхода — единый словарь; на нём ветвятся скиллы, а не на тексте вывода:**
|
||||
**Копия.** Дом словаря — `shared/axes.md` в репозитории плагина: словарь общий
|
||||
для всех скриптов, и ни один скилл им не владеет. Правится дом, а не этот файл.
|
||||
|
||||
| Код | Что случилось | Что делать |
|
||||
| --- | --- | --- |
|
||||
| 0 | сошлось / сделано | дальше по сценарию |
|
||||
| 1 | **только `check`:** найден дрейф индексов и файлов | `check --fix`, остаток разобрать |
|
||||
| 2 | ошибка употребления: аргументы или нарушенное правило | читать сообщение, это отказ по существу |
|
||||
| 3 | окружение: каталог не найден, конфиг битый или мимо диска | чинится путём или `.av-dev.toml` в корне, повтор не поможет |
|
||||
| 4 | внутренний сбой | дефект скрипта, доложить |
|
||||
<!-- копия: коды-выхода из av-dev/shared/axes.md -->
|
||||
|
||||
Различать 1 и 3 обязательно: «дрейф в беклоге» — рабочая ситуация, «каталога
|
||||
нет» — нерабочая, и одинаковая реакция на них была бы неверна в обоих случаях.
|
||||
**Коды выхода — общий словарь всех скриптов `av-dev`. Ветвись на коде, а не на
|
||||
тексте вывода.**
|
||||
|
||||
| Код | Что случилось |
|
||||
| --- | --- |
|
||||
| 0 | сошлось |
|
||||
| 1 | дрейф: рабочая ситуация, чинится |
|
||||
| 2 | ошибка употребления: аргументы или нарушенное правило |
|
||||
| 3 | окружение: не тот каталог, битый конфиг, нет инструмента |
|
||||
| 4 | внутренний сбой — дефект скрипта, доложить |
|
||||
|
||||
**Различать 1 и 3 обязательно.** «Дрейф» — рабочая ситуация, и чинится она
|
||||
правкой предмета; «окружение» — нерабочая, и повтор той же командой не поможет.
|
||||
Одинаковая реакция на них неверна в обоих случаях.
|
||||
|
||||
<!-- /копия: коды-выхода -->
|
||||
|
||||
Здесь это значит: код 1 приходит **только от `check`** — найден дрейф индексов и
|
||||
файлов, чинится `check --fix`, остаток разбирается руками. Код 3 — каталог не
|
||||
найден, конфиг битый или мимо диска: чинится путём или `.av-dev.toml` в корне.
|
||||
|
||||
Тип — английское ключевое слово `goal` / `feature` / `fix` / `chore` /
|
||||
`research` (как и прочие токены команд), у `add` **обязательное**: без него
|
||||
|
||||
@@ -77,15 +77,11 @@ goal | feature | fix | chore | research, по-английски, как и пр
|
||||
|
||||
Каталог задач: `--dir` (обязан быть внутри рабочего каталога) → `tasks/` вверх
|
||||
от текущего каталога. Прежние раскладки (`docs/tasks`, `doc/tasks`) читаются,
|
||||
пока живы непереехавшие проекты; переезд — запись 11 журнала версий канона.
|
||||
пока живы непереехавшие проекты; переезд — запись 11 закрытого журнала канона (changelog-before-merge.md).
|
||||
|
||||
Коды выхода (единый словарь, на нём ветвятся скиллы):
|
||||
|
||||
0 всё сошлось / операция выполнена
|
||||
1 расхождения найдены (только check: дрейф индексов и файлов)
|
||||
2 ошибка употребления: неверные аргументы, нарушенное правило процесса
|
||||
3 окружение: каталог задач не найден, конфиг битый или указывает в никуда
|
||||
4 внутренний сбой (непойманное исключение) — это дефект скрипта
|
||||
Коды выхода — общий словарь скриптов av-dev; дом словаря и разбор «дрейф
|
||||
против окружения» — av-dev/shared/axes.md. Значения — в константах ниже; здесь
|
||||
код 1 приходит только от check.
|
||||
|
||||
Тело задачи (контекст, критерии, вопросы, ссылки) остаётся агенту — add кладёт
|
||||
заголовок, мета-блок и шаблон-плейсхолдер; агент дописывает редактором.
|
||||
|
||||
Reference in New Issue
Block a user