diff --git a/av-dev/skills/code-resolve/SKILL.md b/av-dev/skills/code-resolve/SKILL.md index 10b7c6d..546f165 100644 --- a/av-dev/skills/code-resolve/SKILL.md +++ b/av-dev/skills/code-resolve/SKILL.md @@ -302,10 +302,14 @@ flowchart TD | код — `opsx:apply`, вместе с гейтом до зелёного и поведенческой верификацией | [solve](references/solve.md), шаг 4 | | правки по находкам триажа, помеченным `инлайн` | [solve](references/solve.md), шаг 6; [maintain](references/maintain.md), шаг 4 | | правка оснастки в сценарии обслуживания | [maintain](references/maintain.md), шаг 2 | +| архивация change и синк документации — `opsx:archive` и `av-dev:doc-sync` | [solve](references/solve.md), шаг 7; [maintain](references/maintain.md), шаг 5 | **Остальное остаётся оркестратору, и перечень закрыт:** выбор сценария и стопы, -чекпоинт, вызовы `av-dev:code-review`, `av-dev:doc-sync`, `av-dev-git:commit` и -`av-dev:task-track`, сверка плана с исходом, урожай и доклад. Ни одна из этих +чекпоинт, вызовы `av-dev:code-review`, `av-dev-git:commit` и `av-dev:task-track`, +сверка плана с исходом, урожай и доклад. **Коммит и закрытие задачи агенту не +отдаются ни в одном сценарии** — они необратимы для учёта: закрытие удаляет запись +и правит индексы, а коммит уезжает в историю. Оркестратор делает их сам, уже +сверив план прогона с исходом. Ни одна из этих работ не пишет файлов проекта — они и есть та работа, ради которой контекст берегут. @@ -357,6 +361,11 @@ flowchart TD Диффа, пересказа кода и логов в возврате нет — иначе экономия, ради которой шаг и вынесен, отменяется в момент возврата. +**Чек-лист синка — единственное исключение из «не длиннее экрана».** Он приходит +из хвостового агента целиком и целиком уезжает в доклад: тронутые документы +поимённо, нетронутые — одной строкой с общей причиной. Сжать его своими словами +значит потерять принуждённое отрицание, ради которого шаг и существует. + **Возврату на слово не верят, и перечитывать за агентом дифф для этого не надо.** Верят независимым артефактам: зелёному гейту, отчёту триажа, ревью следующего шага. Своей прозе здесь верить нельзя ровно по той причине, по которой ей не diff --git a/av-dev/skills/code-resolve/references/maintain.md b/av-dev/skills/code-resolve/references/maintain.md index 38f8c82..5818583 100644 --- a/av-dev/skills/code-resolve/references/maintain.md +++ b/av-dev/skills/code-resolve/references/maintain.md @@ -371,11 +371,18 @@ ADR: список источников канон закрыл двумя — а логировать их не надо; `развилка` — вопросом в запись, и агенту она не отдаётся. Отложенные находки собери в секцию доклада `Урожай`; задачи из него заводит `av-dev:task-track`, не ты. -### 5. Синк документации — главный шаг этого сценария +### 5. Синк документации — главный шаг этого сценария, и делает его агент -**Вызови Skill `av-dev:doc-sync`.** Правило то же и такое же жёсткое: -**принуждённое отрицание** — каждый документ канона либо назван обновлённым, либо -получает «не требуется, потому что…». Нетронутые группируются одной строкой. +**Синк уходит агенту** (SKILL.md, «Кто пишет»): работа письменная и нормирована +чек-листом скилла `av-dev:doc-sync`, а не суждением оркестратора. В задании — +корень проекта, база диффа, что было тронуто правкой, требование принуждённого +отрицания и требование довести гейт до зелёного после правок. Вычитку языка +`av-dev:doc-sync` зовёт сам. + +**Правило то же и такое же жёсткое: принуждённое отрицание** — каждый документ +канона либо назван обновлённым, либо получает «не требуется, потому что…». +Нетронутые группируются одной строкой. Возврат приходит в этой же форме и уезжает +в доклад целиком: тронутое без нетронутого не отличается от невыполненного шага. **Здесь этот шаг весит больше, чем в решении, и вот почему.** Обслуживание не меняет поведения — значит, почти всё, что оно меняет, это документация: команды, diff --git a/av-dev/skills/code-resolve/references/solve.md b/av-dev/skills/code-resolve/references/solve.md index 9933f3b..c0a53a2 100644 --- a/av-dev/skills/code-resolve/references/solve.md +++ b/av-dev/skills/code-resolve/references/solve.md @@ -30,13 +30,12 @@ flowchart TD s4["4. opsx:apply — код, гейт,
поведенческая верификация — агентом"] s5["5. разметка — review-scope по диффу:
размер, сложность, метка, план тем"] s6["6. ревью кода по метке
+ отработка замечаний агентом"] - s7["7. opsx:archive"] - s8["8. синк документации — av-dev:doc-sync"] - s9["9. коммит работы — av-dev-git:commit"] - s10["10. закрыть задачу — av-dev:task-track,
вторым коммитом учёта"] + s7["7. opsx:archive + синк документации —
одним агентом"] + s8["8. коммит работы — av-dev-git:commit"] + s9["9. закрыть задачу — av-dev:task-track,
вторым коммитом учёта"] in --> s1 - s1 --> s2 --> s3 --> s4 --> s5 --> s6 --> s7 --> s8 --> s9 --> s10 + s1 --> s2 --> s3 --> s4 --> s5 --> s6 --> s7 --> s8 --> s9 s5 -.->|"план задачи: темы и глубины"| s6 s3 -.->|"скорректировать:
правка спек и дизайна"| s3 s6 -.->|"находка отменяет дизайн:
меняются дельта-спеки"| s3 @@ -326,21 +325,37 @@ flowchart TD единственный **независимый** артефакт о составе прогона: своей прозе здесь верить нельзя — она написана тем же, кто мог проход и пропустить. -### 7. Архивировать — `opsx:archive` +### 7. Архивация и синк документации — одним агентом -Вызови Skill `opsx:archive`: change уезжает в архив, дельты вливаются в -актуальные спеки. Не пропускай `openspec validate --strict` перед этим. +**Оба шага уходят одному агенту, и это один запуск** (SKILL.md, «Кто пишет»). +Работа здесь письменная от начала до конца: `opsx:archive` вливает дельты в +актуальные спеки, `av-dev:doc-sync` правит документы канона, и обе правки идут по +чек-листам своих скиллов, а не по суждению оркестратора. Разнесённые по двум +запускам, они стоили бы двух заданий, двух возвратов и паузы между ними — при том +что второй шаг читает ровно то, что оставил первый. -### 8. Синк документации +В задании: корень проекта, идентификатор change, база диффа и **порядок** — +сначала `opsx:archive` с `openspec validate --strict` перед ним, затем +`av-dev:doc-sync`. Плюс требование довести гейт проекта до зелёного после правок: +документы у многих проектов гейт проверяет, и красный гейт здесь остановил бы +коммит следующим шагом. -**Вызови Skill `av-dev:doc-sync`**: он владеет содержимым документов канона и -ведёт чек-лист синка. +**Вычитку языка зовёт сам `av-dev:doc-sync`** — агента `doc-wording` по пачке +правленых документов. Отдельным запуском её тянуть не надо, и в задании она не +называется: правило живёт в том скилле, а не здесь. -**Правило одно и оно жёсткое: принуждённое отрицание.** Доклад обязан назвать +**Возврат — адреса тронутого, исход валидации, чек-лист синка и исход гейта.** +Чек-лист уезжает в доклад целиком, и переписывать его своими словами нельзя — это +единственный след того, что каждый документ был назван. + +**Правило, которое задаёт его форму, одно и оно жёсткое: принуждённое +отрицание.** Доклад обязан назвать **каждый** документ канона — либо чем он обновлён, либо «не требуется, потому что…». Нетронутые группируются одной строкой с общей причиной. Список триггеров прозой уже проверен на живом проекте и дал 6 записей ADR на 43 изменения; -работает только обязательное отрицание. +работает только обязательное отрицание. **Требование стоит в задании агента** — +без него возврат придёт перечнем тронутого, а тронутое без нетронутого не +отличается от невыполненного шага. **Список документов и их триггеров здесь не дублируется** — он в чек-листе скилла `av-dev:doc-sync`, и копия уже однажды разошлась с оригиналом, потеряв два @@ -351,7 +366,7 @@ flowchart TD задачу нельзя: документ, заведённый мимо канона, окажется вторым домом ровно тому, что канон потом заведёт своим. -### 9. Коммит +### 8. Коммит Коммить **в текущую ветку** (`git rev-parse --abbrev-ref HEAD`), сам ветку не создавай и не переключай, ничего не пушь. @@ -361,14 +376,14 @@ flowchart TD напиши сообщение сам и скажи строкой доклада, что форму коммита не сверял никто. Одна задача — один осмысленный коммит. -### 10. Закрыть задачу — **после коммита, не раньше** +### 9. Закрыть задачу — **после коммита, не раньше** **Вызови Skill `av-dev:task-track`** и попроси закрыть задачу как реализованную — он владеет форматом и двигает строку индекса сам. Путь к его скрипту не выясняй и индексы руками не правь: мост между плагинами — вызов скилла, а не путь. **Порядок обязателен.** Закрытие удаляет файл задачи; сделанное до коммита оно -оставило бы задачу закрытой без единого следа работы, если шаг 9 упадёт. +оставило бы задачу закрытой без единого следа работы, если шаг 8 упадёт. **Закрытие тоже коммитится — вторым коммитом, тут же.** Удаление файла задачи и правка индексов (их имена знает `av-dev:task-track`, не ты) — это правки в рабочем diff --git a/decisions/75-tail-in-one-agent.md b/decisions/75-tail-in-one-agent.md new file mode 100644 index 0000000..0ecc893 --- /dev/null +++ b/decisions/75-tail-in-one-agent.md @@ -0,0 +1,60 @@ +# 75. Хвост задачи — один агент: архивация и синк вместе (2026-08-23) + +## Что было + +Хвост сценария решения шёл четырьмя вызовами подряд: `opsx:archive`, +`av-dev:doc-sync`, `av-dev-git:commit`, `av-dev:task-track`. Первые два — +письменная работа, и оба уже уходили агентам ([тема 72](72-writing-delegated-to-agents.md)), +но **разными запусками**: два задания, два возврата и пауза оркестратора между +ними. + +Замер по прогонам в проекте transcriber 22–23 августа: архивация 5 минут, синк +документации 14 минут, паузы оркестратора между шагами хвоста — около 3 минут на +прогон. В соседней сессии те же два шага, отданные одному агенту, заняли один +запуск на 29 минут вместо двух. + +## Решено + +**Р287. Архивация и синк уходят одному агенту, одним запуском.** Второй шаг +читает ровно то, что оставил первый: `opsx:archive` вливает дельты в актуальные +спеки, `av-dev:doc-sync` сверяет с ними документы канона. Разнесённые по двум +заданиям, они дважды платят за сбор одного и того же контекста. + +**Р288. Порядок внутри задания назван, а не выведен.** Сначала `opsx:archive` с +`openspec validate --strict` перед ним, затем `av-dev:doc-sync`. Синк по +неархивированному change сверял бы документы с дельтами, которых в актуальных +спеках ещё нет. + +**Р289. Гейт после правок документов доводит до зелёного тот же агент.** Многие +проекты проверяют документы гейтом, и красный гейт остановил бы коммит следующим +шагом — то есть отказ обнаружился бы у оркестратора, которому чинить его нечем +без второго задания. + +**Р290. Коммит и закрытие задачи агенту не отдаются ни в одном сценарии.** +Закрытие удаляет запись задачи и правит индексы, коммит уезжает в историю — оба +необратимы для учёта. Оркестратор делает их сам, уже сверив план прогона с +исходом; правило необратимого ([тема 72](72-writing-delegated-to-agents.md), Р268) +остаётся в силе целиком. + +**Р291. Чек-лист синка — единственное исключение из «возврат не длиннее экрана»** +([тема 72](72-writing-delegated-to-agents.md), Р269). Он приходит целиком и целиком +уезжает в доклад: тронутые документы поимённо, нетронутые — одной строкой с общей +причиной. Сжатый своими словами, он теряет принуждённое отрицание, ради которого +шаг и существует. + +**Р292. В обслуживании синк тоже уходит агенту.** Там он главный шаг сценария и +идёт без архивации — change у обслуживания нет по построению. + +## Следствия + +**С261. Требование принуждённого отрицания переехало в задание.** Раньше оно +адресовалось оркестратору, который звал `doc-sync` сам; теперь его обязан нести +текст задания — иначе возврат придёт перечнем тронутого, а тронутое без +нетронутого неотличимо от невыполненного шага. + +**С262. Вычитку языка отдельным запуском больше не зовут.** `av-dev:doc-sync` +зовёт `doc-wording` сам, по пачке правленых документов; в задании она не +называется, потому что правило живёт в том скилле. + +**С263. Шагов в сценарии решения стало девять.** Архивация и синк слились в +седьмой; коммит стал восьмым, закрытие задачи — девятым. diff --git a/decisions/README.md b/decisions/README.md index 1526641..d09a789 100644 --- a/decisions/README.md +++ b/decisions/README.md @@ -126,3 +126,4 @@ | 72 | [Письмо уходит агентам: оркестратор ставит задание и читает возврат](72-writing-delegated-to-agents.md) | 2026-08-22 | | 73 | [Гейт, прогнанный до ревью, не гоняется второй раз](73-gate-run-reused-by-fingerprint.md) | 2026-08-23 | | 74 | [Ревью дизайна снято, разметка переехала за код](74-design-review-dropped-scope-after-code.md) | 2026-08-23 | +| 75 | [Хвост задачи — один агент: архивация и синк вместе](75-tail-in-one-agent.md) | 2026-08-23 |