sdd-power

---
name: sdd-power
description: "Дисциплина разработки по существующей документации с персистентным трекингом (PLAN.md, WORKLOG.md, TIMELINE.md, LESSONS.md, stages/ в docs/sdd-power/), валидатором трекинга и критической проверкой документации на ошибки. Используй ВСЕГДА, когда пользователь говорит «начни разработку по документации/по ТЗ», «продолжи разработку», «где мы остановились», «что сделано, что осталось», «сверься с планом», «обнови план и лог», «проверь трекинг», «закрой этап», «веди план/таймлайн разработки», «инициализируй трекинг»; упоминает PLAN.md, WORKLOG.md, TIMELINE.md, LESSONS.md, stages/ или docs/sdd-power; жалуется, что документация проекта содержит ошибки, устарела или расходится с кодом; или начинает многосессионную разработку. Триггерься и без явного упоминания трекинга, если в проекте есть docs/sdd-power, якорь sdd-power в CLAUDE.md или файлы PLAN.md и WORKLOG.md в корне (след старой версии). НЕ используй для разовых мелких правок в одну сессию и для написания ТЗ с нуля: скилл работает по уже существующей доке."
---

# SDD Power

Скилл для длительной разработки по существующей проектной документации. Решает две проблемы:

1. **Потеря состояния между сессиями.** Контекст обнуляется, и через неделю никто (включая тебя) не помнит, что сделано, что осталось и почему приняли то или иное решение. Лечится персистентными файлами трекинга, которые ведутся синхронно с кодом.
2. **Слепое доверие документации.** Документацию писали люди, она устаревает и содержит ошибки. Слепое исполнение ошибочной доки создаёт баги, которые потом трудно объяснить. Лечится протоколом критической проверки с объективными критериями.

Оба принципа работают только при дисциплине — «допишу потом» разрушает систему за две сессии.

**Главное правило скилла: трекинг существует на диске или не существует вовсе.** План, изложенный в чате, исчезает вместе с сессией; сколько бы ни было написано в ответе, работа считается несделанной, пока файлы не лежат в `docs/sdd-power/`. Поэтому инфраструктура разворачивается **первым действием** — до изучения доки, до плана, до вопросов пользователю.

---

## Шаг 1: развернуть инфраструктуру (всегда первым)

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

```bash
# путь к скиллу берётся из его location; если не уверен — найди:
SDD=$(dirname "$(find ~/.claude /mnt/skills . -maxdepth 6 -name SKILL.md -path '*sdd-power*' 2>/dev/null | head -1)")

bash "$SDD/scripts/sdd.sh" init --name "<название проекта>"   # новый проект или подъём старого
bash "$SDD/scripts/sdd.sh" check                              # в начале каждой сессии: инфраструктура + дрейф доки + ошибки трекинга
bash "$SDD/scripts/sdd.sh" next                               # где остановились и что следующее
bash "$SDD/scripts/sdd.sh" validate                           # полный разбор содержания файлов трекинга
bash "$SDD/scripts/sdd.sh" snapshot --docs "docs/ТЗ.md ..."   # зафиксировать снимок документации
bash "$SDD/scripts/sdd.sh" stage <ID> <slug>                  # заготовка саммари при закрытии этапа
bash "$SDD/scripts/sdd.sh" archive-tasks <ID>                 # перенести состав закрытого этапа из PLAN в саммари
```

Корень проекта скрипт берёт из `git rev-parse --show-toplevel`, иначе — текущая директория; задать явно — `--root DIR`. Ключ `--gitignore` добавляет `docs/sdd-power/` в `.gitignore` (см. «Git» ниже, по умолчанию — не добавляет).

**Скрипт недоступен** (нет bash, скилл лежит без `scripts/`) — сделай то же руками, это шесть команд:

```bash
mkdir -p docs/sdd-power/stages && touch docs/sdd-power/stages/.gitkeep
cp "$SDD/assets/PLAN.template.md"     docs/sdd-power/PLAN.md
cp "$SDD/assets/WORKLOG.template.md"  docs/sdd-power/WORKLOG.md
cp "$SDD/assets/TIMELINE.template.md" docs/sdd-power/TIMELINE.md
cp "$SDD/assets/LESSONS.template.md"  docs/sdd-power/LESSONS.md
ls -R docs/sdd-power/
```

Ручной путь не ставит якорь — допиши его в `CLAUDE.md` сам (и в `AGENTS.md`, если он есть), иначе проект не подхватится в следующей сессии: строка `<!-- sdd-power -->`, ниже — где лежит трекинг и что читать его в начале сессии.

**Гейт.** Первый ответ пользователю в этой сессии обязан содержать вывод `check` (или список созданных файлов). Нет вывода — значит, ты не развернул инфраструктуру, а рассказал о ней; вернись и разверни. Не переходи к изучению документации, плану и коду, пока `check` не показал «инфраструктура на месте».

**Где файлы.** Всегда `docs/sdd-power/` относительно корня проекта: `PLAN.md`, `WORKLOG.md`, `TIMELINE.md`, `LESSONS.md`, `stages/`. Не корень: он и так перегружен, а отдельная директория делает трекинг переносимым.

**Якорь в CLAUDE.md.** Скрипт дописывает туда блок с меткой `<!-- sdd-power -->` — это главный механизм подхвата старых проектов: в сессии, где скилл не сработал по фразе пользователя, CLAUDE.md читается автоматически, и по нему скилл активируется. Якорь потерян — проект перестаёт подхватываться, поэтому `check` проверяет его каждую сессию. Есть `AGENTS.md` — блок дублируется и туда.

**Git.** По умолчанию `docs/sdd-power/` **версионируется вместе с кодом**: файлы переживают свежий клон, видны коллегам и откатываются вместе с веткой. Плата — шум в диффах PR. Если пользователь предпочитает чистые диффы, запусти `init --gitignore` и предупреди о следствии: файлы не переживут клон и не видны никому, кроме этой машины, поэтому всё важное команде (решения, ограничения, исправления доки) обязано доезжать до кода, документации или CLAUDE.md.

**Нет проекта на диске** (разговор в чате, файлы трекинга пришли вложениями) — разверни инфраструктуру в рабочей директории, которую видит пользователь, и отдай файлы ему в конце сессии. Присланные PLAN/WORKLOG/TIMELINE/LESSONS положи на их места (`init` подхватит и не затрёт) и работай в режиме продолжения: это состояние проекта, а не справочный материал.

---

## Шаг 2: документация и режим

**Где документация проекта.** Если пользователь назвал путь — используй его. Если нет, ищи в порядке убывания вероятности: `docs/`, `documentation/`, `spec/`, `specs/`, `*-docs/`, README и вложенные `*.md` в корне. Нашёл однозначного кандидата — работай с ним и скажи об этом пользователю. Нашёл несколько или ничего — спроси, не угадывай: работа не по той документации хуже, чем один уточняющий вопрос.

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

**Режим** определяется тем, что напечатал `check`:

| Что видишь | Режим |
|---|---|
| Файлы созданы пустыми из шаблонов | **Инициализация** |
| Файлы содержательны (свои задачи, записи) | **Продолжение** |
| Файлы содержательны, но противоречат коду | **Продолжение**, начиная с восстановления актуальности |

Файлы трекинга ищи не только там, где ждёшь: `init` подбирает их из корня, `docs/`, `.sdd/`, `sdd-power/`. Если `check` сообщил о файлах вне `docs/sdd-power/` — это след старой версии скилла, перенеси и отметь миграцию записью в WORKLOG.

---

## Режим инициализации

Инфраструктура уже развёрнута шагом 1 — файлы лежат на диске пустыми, дальше их наполняют.

1. **Изучи документацию целиком, критическим взглядом.** Не бегло — ты строишь на ней весь план. По ходу отмечай противоречия, неоднозначности и места, расходящиеся с фактическим кодом.
   **Проверь и молчание доки.** Ошибки — не единственный дефект: пройдись по тому, о чём документация не говорит из того, что реализации понадобится (обработка ошибок, крайние объёмы, миграция существующих данных, права доступа — что применимо). Незамеченный пробел всплывает посреди реализации, когда менять подход дорого; замеченный — это строка в «Открытых вопросах» или осознанное допущение в плане.
2. **Заполни PLAN.md на диске** — правь файл, а не сочиняй план в ответе. Этапы и задачи со ссылками на разделы документации, на которых они основаны. Ссылка обязательна — она даёт возможность перепроверить задачу, когда дока изменится.
   **Покрытие в обе стороны:** пройдись по документации и проверь, что каждое её требование либо покрыто задачей, либо явно внесено в раздел плана «Вне объёма» с причиной. Ссылки задач гарантируют «каждая задача основана на доке», но не «вся дока разложена на задачи» — требование, потерянное на этом шаге, не всплывёт до самого конца.
   **DoD этапа:** у каждого этапа — строка Definition of Done: наблюдаемое состояние проекта после закрытия этапа, проверяемое командами. Это критерий целого, который не сводится к сумме галочек задач.
   **Номер и гранулярность:** номер задачи — `<этап>.<N>` (1.1, 1.2, 2.1), он обязателен: по нему на задачу ссылаются WORKLOG и LESSONS, по нему валидатор сверяет закрытие. Одна задача ≈ один коммит и одна рабочая сессия. Задача, которую нельзя завершить за сессию, месяцами висит в `[~]`, и трекинг перестаёт отражать реальность — декомпозируй такие сразу.
3. **Заполни TIMELINE.md**: по одной строке на этап из плана, статусы пока пустые. Затем зафиксируй снимок документации: `sdd.sh snapshot --docs "<файлы доки>"` — с этого момента `check` сам заметит, что дока изменилась, и потребует ре-синхронизации плана.
4. **Внеси найденные проблемы** в разделы PLAN.md «Расхождения с документацией» и «Открытые вопросы».
   Вопросы, чей ответ меняет архитектуру или модель данных, не оставляй висеть в таблице — разбери их с пользователем до подтверждения плана, по одному за раз, в порядке убывания влияния. До начала кода эти ответы почти бесплатны; после — каждый стоит переделки.
5. **Сделай первую запись в WORKLOG.md** — «трекинг развёрнут, план составлен по такой-то доке», с числом этапов, задач и найденных расхождений. Сессия может оборваться на подтверждении плана; после этой записи следующая начнётся не с нуля.
6. **Прогони `sdd.sh validate`** и почини ошибки: этап без DoD, этап в плане без строки в TIMELINE, задача без номера. План с ошибками структуры не показывают — его нечем будет закрывать.
7. **Покажи пользователю план и найденные расхождения и дождись подтверждения.** Не начинай реализацию до ответа: неверно понятый план стоит дороже, чем минута ожидания. Показывай план решениями вперёд: сначала то, что пользователь вероятнее всего захочет поменять (модель данных, интерфейсы, пользовательские потоки), механическую часть — в конец. Задачу с критерием «узнаю, когда увижу» (интерфейс, тексты, визуал) начинай с дешёвого прототипа на реакцию пользователя, а не с полной реализации: правка прототипа стоит минуты, правка встроенной реализации — задачу.

---

## Режим продолжения

Начало **каждой** сессии, до любого кода:

1. **`sdd.sh check`** — шаг 1 уже сделан, здесь ты убеждаешься, что цела инфраструктура и непротиворечиво содержание. Он отвечает сразу на три вопроса: все ли файлы на месте, не разошлась ли документация со снимком, нет ли ошибок в самих файлах трекинга. Каждый ответ требует своего действия:
   - недостающее в инфраструктуре (нет `stages/`, потерян якорь в CLAUDE.md, файлы в корне) — почини через `init`, отметь миграцию одной записью в WORKLOG;
   - **дока изменилась с момента снимка** — не продолжай по памяти: сравни изменившиеся разделы с планом, обнови задачи, зафиксируй ре-синхронизацию в WORKLOG и сделай `sdd.sh snapshot`;
   - **ошибки трекинга** — почини до кода; предупреждения разбери через `sdd.sh validate`.
   Отдельно: в файлах может не быть полей текущих шаблонов («Коммит», «Проверено», «DoD этапа») — старые записи не переписывай, просто веди новые по актуальному шаблону.
2. Прочитай PLAN.md, TIMELINE.md, LESSONS.md целиком и верхние записи WORKLOG.md. По закрытым этапам читай `stages/<ID>-<имя>.md`, а не ленту ворклога за те дни — саммари для того и написано.
3. **Сверь их с фактическим состоянием кода.** Файлы могут врать: работу могли делать вручную, мимо тебя. Расхождение нашёл — сначала приведи файлы в актуальное состояние, отметь это в WORKLOG.md, и только потом продолжай.
4. **Разбери незакрытые `[~]`.** Статус «в работе» означает, что прошлая сессия оборвалась на середине: не верь статусу, проверь код. Определи, что реально сделано, что сделано наполовину, что не начато, и приведи задачу к честному состоянию — доделай, откати или переразбей. Недоделанная работа, принятая за готовую, — самый дорогой сорт ошибки в этой системе.
5. **`sdd.sh next`** — печатает текущий этап, его DoD, прогресс и следующую задачу целиком, плюс заготовку записи WORKLOG. Это не замена чтению файлов, а страховка: после `/compact` или в оборванной сессии он за одну команду возвращает точку, на которой остановились.
6. Скажи пользователю в 1–3 предложениях: где остановились, что идёт следующим.

**После сжатия или очистки контекста** (`/compact`, `/clear`, длинная сессия) перечитай файлы трекинга, прежде чем продолжать. Признак, что пора: не помнишь деталей текущей задачи или последних принятых решений. Дешевле перечитать, чем сделать работу второй раз или мимо плана.

LESSONS.md читай всегда и целиком — он существует ровно для того, чтобы ты не повторил уже разобранную ошибку.

---

## Критическое отношение к документации

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

**Ошибка** — только то, что можно объективно доказать:

- внутреннее противоречие (два раздела требуют несовместимого);
- противоречие фактическому коду, API, схеме данных или версии зависимости;
- технически невыполнимое или заведомо неработающее решение;
- очевидная опечатка при однозначно восстановимом верном варианте (имя поля, метода, эндпоинта).

**Не ошибка:** «я бы сделал иначе», «так не принято», «есть способ лучше», «устаревший подход, но рабочий». Это предложения. Следуй документации, а идею запиши в PLAN.md → «Предложения по улучшению». Решение о смене подхода принимает пользователь, не ты.

**Протокол при находке** — три уровня по цене ошибки:

| Тип | Действие |
|---|---|
| Опечатка, исправление однозначно | Исправь сам → WORKLOG.md + «Расхождения» в PLAN.md → продолжай |
| Затрагивает архитектуру, поведение системы, контракты API, или вариантов исправления несколько | Остановись по этой задаче, изложи проблему и варианты, спроси пользователя. Пока ждёшь — бери независимые задачи плана |
| Вкусовое несогласие | Следуй доке, запиши в «Предложения по улучшению» |

Каждое подтверждённое расхождение — кандидат в LESSONS.md: если дока в этом месте врёт, ты рискуешь снова поверить ей в следующей сессии.

**Снимок документации.** План строится на конкретном состоянии доки — зафиксируй его дважды: датой/версией в шапке PLAN.md (для человека) и командой `sdd.sh snapshot --docs "<файлы>"` (для машины: пути и хеши уезжают в `config.yml` и `docs.lock`). Дальше дрейф ловится сам — `check` каждую сессию сверяет хеши и говорит, какой файл доки изменился; расхождение даты в шапке и в конфиге он тоже заметит. Числа и объёмы из доки считай снимком на эту дату, а не вечной истиной. Если документация изменилась (пользователь принёс новую версию, дока правится параллельно), не продолжай по памяти: сравни изменившиеся разделы с планом, обнови затронутые задачи и снимок в шапке, зафиксируй ре-синхронизацию записью в WORKLOG. Молчаливая работа по устаревшему плану — тот же сорт ошибки, что работа по ошибочной доке.

**Исправления доезжают до самой доки.** Подтверждённое расхождение, оставшееся только в таблице PLAN, продолжает врать каждому следующему читателю документации. Если дока лежит в репозитории — предложи пользователю правку самой доки (или внеси, если он делегировал это явно) и отметь в таблице расхождений, что источник исправлен. Таблица — журнал находок, а не постоянное место жительства истины.

Разбор пограничных случаев и примеры — `references/docs-verification.md`. Читай, когда сомневаешься, ошибка перед тобой или вкусовщина.

---

## Файлы трекинга и их роли

Роли не пересекаются — это защита от дублирования одного и того же в нескольких местах.

| Файл | Отвечает на вопрос | Природа |
|---|---|---|
| **PLAN.md** | Что предстоит сделать? | Живой документ, переписывается |
| **WORKLOG.md** | Что и почему было сделано? | Append-only, новые записи сверху |
| **TIMELINE.md** | Где мы в целом? | Таблица этапов, обновляется по статусам |
| **LESSONS.md** | На чём мы уже обжигались? | Курируемый, дистиллированный |
| **stages/\<ID\>-\<имя\>.md** | Что представляет собой закрытый этап? | Пишется один раз при закрытии этапа |

Форматы — в `assets/`. Не изобретай свои: единый формат между проектами экономит время при возврате к старому коду. Формат — не украшение: по нему работает валидатор, и отступление от него делает файлы непроверяемыми.

### Состав скилла

| Файл скилла | Когда нужен |
|---|---|
| `scripts/sdd.sh` | Запускается на каждой сессии; читать не нужно, `sdd.sh help` печатает команды |
| `scripts/validate.awk`, `scripts/next.awk` | Вызываются из `sdd.sh`; отдельно не запускаются |
| `assets/PLAN.template.md`, `WORKLOG.template.md`, `TIMELINE.template.md`, `LESSONS.template.md` | Разворачиваются командой `init`; открывай, когда сомневаешься в формате поля |
| `assets/STAGE.template.md` | Разворачивается командой `stage` при закрытии этапа |
| `references/docs-verification.md` | Читай, когда сомневаешься: перед тобой ошибка доки или вкусовщина |

### Валидатор: правила, ставшие проверкой

`sdd.sh validate` проверяет не наличие файлов, а их содержание, и делит находки на два уровня. **Ошибки** — то, из-за чего система перестаёт работать как задумано: этап без DoD (нечем закрывать), этап в PLAN без строки в TIMELINE (положение дел врёт), этап «завершён» без саммари в `stages/`, задача без номера `<этап>.<N>` (её нечем сверить с WORKLOG). **Предупреждения** — то, что разбирают, но что не блокирует работу: задача `[x]`, чей номер не встречается в WORKLOG; задача без основания в доке или без строки «Проверка»; статус вне разрешённого набора; больше трёх задач в `[~]`; запись WORKLOG длиннее бюджета; LESSONS за пределами 20 правил; дата снимка в PLAN и в конфиге разошлись.

Строгость растёт по мере приближения: у этапа, который ещё «детализируется при подходе», отсутствие DoD и проверок — предупреждение, у этапа в работе — ошибка. Это тот же принцип, по которому будущие этапы плана пишут крупными мазками.

Запускать: в начале сессии (внутри `check`), после ручных правок файлов и обязательно перед закрытием этапа. Смысл ровно тот, что и в правиле про LESSONS: правило, нарушение которого детектируется механически, не должно жить текстом.

### stages/: закрывающее саммари этапа

Директория создаётся вместе с остальной инфраструктурой и до первого закрытого этапа стоит пустой — это нормально, но её отсутствие означает, что `init` не отработал.

При закрытии этапа заведи файл командой `sdd.sh stage <ID> <slug>` (создаст `docs/sdd-power/stages/<ID>-<имя>.md` из шаблона) и заполни его. Это **сжатие** записей WORKLOG за период этапа, а не второй рассказ о той же работе: WORKLOG остаётся телеграфным, развёрнутая картина живёт здесь. Написав саммари, к ленте ворклога за этот период больше не возвращаются — на вопрос «что там в этапе 2 и как это проверить» отвечает один файл на 40 строк вместо десяти хронологических записей.

Раздел «Состав этапа» дописывается в конец саммари командой `archive-tasks` — это архив задач с их номерами, а не второй пересказ; читают его редко, но именно он отвечает на вопрос «что именно входило в этап 2».

Раздел «Важно знать дальше» — место для локального знания: граблей и договорённостей, важных соседним этапам, но не тянущих на общее правило проекта. Это разгружает LESSONS.md, у которого жёсткий бюджет: туда идёт только то, что применимо ко всему проекту.

Этап закрыт — поставь git-тег `stage/<ID>`: состояние кода на момент закрытия этапа поднимается одной командой, без раскопок хешей по записям WORKLOG.

### LESSONS.md: правила, а не история багов

Главное отличие от WORKLOG: сюда попадают не события, а **обобщённые правила, применимые к будущему коду**. История «был баг, починили» уже есть в ворклоге и ничему тебя не учит.

Плохо: `Баг #14: падал экспорт на больших отчётах. Закрыт 12.03.`
Хорошо: `Не буферизуй полный результат запроса перед экспортом — на отчётах >10MB процесс падал по OOM (WORKLOG 12.03). Используй стриминг.`

Второе можно применить, первое — нет.

**Когда писать.** Закрыв баг или разобрав расхождение с докой, спроси себя: может ли эта ошибка повториться в другом месте проекта? Есть ли обобщаемое правило? Если да — запись. Если нет (разовая опечатка, случайность) — хватит WORKLOG.

**Бюджет: не более 20 правил и ~120 строк.** Ты читаешь файл целиком каждую сессию: разросшаяся свалка перестаёт работать, внимание размывается, и правила перестают действовать. Продуктивный день легко даёт 15–20 правил, поэтому лимит достигается быстро и это нормально.

**Упёрся в лимит — сначала консолидируй, потом добавляй.** Порядок действий: удали устаревшие правила (код переписан, дока исправлена) с пометкой в WORKLOG, почему; объедини правила про один класс ошибки в одно с несколькими причинами; перенеси ставшие универсальными для проекта в CLAUDE.md, откуда они подхватываются автоматически. Правило, которое не удаётся ни обобщить, ни выбросить, вытесняет более слабое — приоритет у того, чья ошибка дороже.

**Сильнейшая форма консолидации — превратить правило в проверку.** Правило, нарушение которого детектируется механически, не должно жить текстом: закодируй его тестом, линтер-правилом или проверкой в CI и удали из LESSONS со ссылкой на проверку. «Доступность слота — по `available_persons`, не по `is_available`» текстом полагается на память будущей сессии, а тестом ловит нарушение всегда и бесплатно. Текст — для правил суждения, которые проверкой не выразить.

---

## Закрытие этапа

Все задачи этапа `[x]` — не переходи к следующему, пока не выполнен ритуал закрытия. Он занимает несколько минут и делает этап единицей, к которой можно вернуться:

1. **Прогони DoD этапа** — команды из его строки в PLAN.md, целиком, а не по памяти отдельных задач. Задачи по одной могли пройти, а этап как целое — нет. Красный прогон — это цикл, а не вердикт: чини и перегоняй до зелёного, только зелёный результат идёт в раздел «Как проверить» саммари. Не выходит починить — этап остаётся открытым, проблема эскалируется пользователю; закрытого этапа с красным DoD не существует.
2. **Верификация в трёх измерениях** — DoD отвечает на вопрос «работает ли», верификация на вопрос «то ли это, что планировали». Пройди по коду и артефактам этапа и заполни раздел «Верификация» саммари:
   - **полнота** — все задачи закрыты, все требования доки по этапу реализованы, крайние случаи из «Проверки» покрыты;
   - **корректность** — поведение отвечает намерению документации, а не только букве проверки;
   - **когерентность** — решения, записанные в WORKLOG, действительно отражены в коде: «решили одно, в коде другое» — самая дорогая находка, потому что незаметна для тестов.
   Уровни находок: **критично** блокирует закрытие; **предупреждение** не блокирует, но обязано осесть задачей в PLAN или строкой в «Важно знать дальше» — молча проглоченное предупреждение равносильно его отсутствию; **предложение** уходит в «Предложения по улучшению».
3. **Саммари:** `sdd.sh stage <ID> <slug>` и заполнить — сжатие ворклога за период этапа.
4. **Перенос состава:** `sdd.sh archive-tasks <ID>` — задачи закрытого этапа уезжают из PLAN.md в саммари, в плане остаётся заголовок с пометкой «закрыт» и ссылкой. PLAN читается целиком каждую сессию, и он обязан отвечать на вопрос «что предстоит», а не хранить историю; номера задач в саммари сохраняются дословно, поэтому ссылки из WORKLOG и LESSONS продолжают работать. Команда делает резервную копию `PLAN.md.bak` и отказывается работать дважды.
5. **Git-тег** `stage/<ID>` на текущем коммите. Проект не под git — пропусти шаг и отметь это в саммари: без тега единственная точка возврата к состоянию этапа — даты записей WORKLOG.
6. **TIMELINE.md** — статус `завершён`, дата, ссылка на саммари; обнови «Текущее положение».
7. **PLAN.md** — проверь, что таблицы расхождений, вопросов и находок не остались висеть в открытых статусах по закрытым задачам, а подтверждённые исправления доки этапа предложены к внесению в саму документацию.
8. **LESSONS.md** — момент для консолидации: этап дал новые правила, часть старых устарела, и это лучшая точка проверить бюджет.
9. **`sdd.sh validate`** — зелёный прогон подтверждает, что после всех перестановок файлы не противоречат друг другу.

---

## Правила обновления

- **Обновляй файлы в тот же момент, что и код.** Завершил шаг → сразу запись в WORKLOG.md, чекбокс в PLAN.md, статус в TIMELINE.md. Отложенное обновление — главная причина, по которой такие системы умирают: один раз «допишу потом», и файлам больше нельзя доверять, а значит, они бесполезны.
- **Записывай хеш коммита в WORKLOG.** Сделал коммит — впиши его короткий SHA в запись. Это мост между журналом решений и историей репозитория: по нему поднимается точный дифф под запись «почему сделали так». Если трекинг вынесен из git (`--gitignore`), этот хеш — единственная связь между ними.
- **Закрыл задачу — пройди по таблицам PLAN.md.** Задача почти всегда закрывает что-то ещё: расхождение с документацией переходит в «исправлено», открытый вопрос — в «решён», находка из «Найдено попутно» — в сделанную. Это самое частое место рассинхронизации: чекбокс переставить легко, а таблицы ниже остаются висеть в «ожидает реализации» неделями, и им перестают верить. Номера строк в таблицах не переиспользуй и не переупорядочивай — на них ссылаются WORKLOG и LESSONS.
- **Любое изменение отражай во всех затронутых файлах синхронно.** Новая задача, отмена, смена подхода, подтверждённое расхождение с докой — так, чтобы файлы не противоречили друг другу. Причину фиксируй в WORKLOG.md: через месяц важно не только *что* поменялось, но и *почему*.
- **Держи запись WORKLOG в пределах ~20 строк.** В «Решения и причины» идут только те решения, которые неочевидны из кода и которые будущий читатель иначе откатит как случайные. Всё, что видно в диффе, там уже есть — за этим стоит хеш коммита. Запись на полсотни строк никто не дочитает, а на её написание уходит время, отнятое у работы.
- **Не откладывай запись до конца сессии.** Сессия может оборваться в любой момент — именно на этот случай вся система и построена.

---

## Критерий завершённости шага

Шаг считается сделанным, только когда выполнено всё:

1. **Работоспособность подтверждена наблюдаемым результатом** — прогнанные тесты, вывод запущенной команды, проверенное поведение. «Должно работать», «выглядит корректно», «изменение тривиальное» доказательствами не являются: отметка `[x]` без проверки — это и есть тот случай, когда файлы начинают врать, а вранью в них цена нулевая. Проверить в принципе нечем — оставь `[~]` с пометкой «не верифицировано» и скажи об этом пользователю.
2. Код соответствует документации — либо задокументированному и обоснованному отклонению от неё.
3. PLAN.md, WORKLOG.md, TIMELINE.md обновлены **на диске**, а LESSONS.md пополнен, если появился обобщаемый урок. Записал в ответе, но не в файл — шаг не сделан. Номер задачи должен встретиться в записи WORKLOG: по нему валидатор сверяет, что за галочкой стоит работа.

В конце каждого шага — 1–2 предложения пользователю: что сделано и что следующее по плану. Коротко: подробности он прочтёт в файлах.

---

## Держи скоуп

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

Заметил — заведи задачу в PLAN.md и иди дальше. Единственное исключение: находка физически блокирует текущую задачу; тогда чини минимально необходимым и фиксируй в WORKLOG, почему пришлось выйти за рамки.

---

## Чего не делать

- Не веди трекинг в ответе вместо файлов и не откладывай развёртывание «до подтверждения плана»: несозданный файл — несделанная работа.
- Не начинай код до изучения документации и подтверждения плана.
- Не отклоняйся от документации без доказанной ошибки и записи о ней.
- Не отмечай задачу сделанной без наблюдаемого подтверждения.
- Не дублируй содержимое файлов друг в друге — у каждого своя роль.
- Не превращай LESSONS.md в журнал багов.
- Не спрашивай подтверждения на каждый шаг: пользователь подтверждает начальный план и архитектурные развилки, остальное — твоя работа.
- Не разворачивай всю церемонию ради разовой мелкой правки — для неё скилл не нужен.