Дисциплина планов — проектно-локальная эфемерная рабочая память

Каноническая нормативная ссылка для нижестоящих участников. Этот документ зеркалирует раздел «Дисциплина планов» спецификации проекта (Spec §3); это автономная ссылка, поставляемая с опубликованным репозиторием. Введённая здесь дисциплина является основополагающей; каждая директива ниже — это MUST, если явно не указано иное. Архитектурное обоснование зафиксировано в ADR-0001.

1. Определение и границы

План — это любой намеренный, преходящий рабочий артефакт, созданный в процессе рассуждения о проекте, включая, но не ограничиваясь:

• Архитектурные наброски, разборы системного дизайна, декомпозиции компонентов.
• Структуры разбиения работ, многошаговые списки задач, деревья декомпозиции.
• Стратегии рефакторинга, разборы миграций, последовательности выкатки.
• Журналы отладки, логи гипотез, заметки о воспроизведении.
• Заметки об исследовании, описания спайков, черновики промптов, транскрипты harness, сохранённые для дальнейшего использования.
• Любой документ, написанный, чтобы думать с его помощью, а не чтобы выпустить.

Планы категориально отличаются от этих смежных классов:

Планы предшествуют ADR. Когда план сходится к долговечному решению, это решение повышается до ADR (§4 Жизненный цикл); сам план архивируется или отбрасывается.

2. Расположение, видимость и именование

• Путь. <project-root>/.apothem/plans/ — единственный канонический дом. Устаревшее дерево <project-root>/.plans/ больше не является каноническим — обновите его командой apothem migrate-workspace (§5). Не директория конфигурации harness (например, ~/.claude/plans/, ~/.claude/.plans/ или ~/.codex/.plans/). Не черновая папка на рабочем столе. Не ~/notes/. Не tmp/plans/.
• Видимость. Папка зарегистрирована в .gitignore проекта согласно канонической вставке из §6. Среда выполнения harness ДОЛЖНА проверять наличие этой записи перед любой записью; при её отсутствии добавляет запись с однострочным заголовочным комментарием и ссылкой на этот документ.
• Соглашение об именовании файлов. YYYY-MM-DD--<kebab-case-slug>.md. Для более крупных рабочих пространств — субкатегоризируйте в .apothem/plans/<area>/YYYY-MM-DD--<slug>.md.
  • Примеры: .apothem/plans/2026-04-30--auth-refactor-strategy.md, .apothem/plans/api/2026-04-30--rate-limit-rollout.md.
• Индекс. Опциональный .apothem/plans/INDEX.md (также в gitignore) может агрегировать ссылки и статусы; если присутствует, среда выполнения harness поддерживает его при каждой записи плана.
• Архив. Сошедшиеся или заброшенные планы перемещаются в .apothem/plans/_archive/. Никогда не удаляются без явного подтверждения через структурированный запрос.
• Заголовок авторства в планах. Планы освобождены от SPDX-строки заголовка авторства (согласно site/content/docs/reference/authorship-header.mdx §Список исключений). Это эфемера в gitignore; применение постоянного маркера происхождения к преходящей рабочей памяти — категориальная ошибка. Frontmatter (§3) несёт происхождение плана.

3. Схема frontmatter (валидируемая)

Каждый файл плана несёт:

---
title: <human-readable title>
project: <git-remote-url-or-canonical-local-path>
created: <ISO-8601 timestamp>
updated: <ISO-8601 timestamp>
status: draft | in-progress | converged | abandoned
tags: [<kebab>, ...]
supersedes: <prior-plan-relative-path or null>
promotes-to: <ADR path or null>
---

JSON Schema для планов находится в src/apothem/schemas/plan.schema.json. Слеш-команда /plan (и валидатор plans-discipline-language) проверяет на соответствие ей при каждой записи.

4. Жизненный цикл и рабочий процесс повышения

1. Черновик — первоначальное создание; status: draft.
2. В работе — активно итерируется; status: in-progress; updated обновляется при каждой существенной правке.
3. Сходимость — кристаллизуется долговечное решение:
   1. Извлеките решение в новый ADR в ратифицированном проектом расположении ADR.
   2. Установите promotes-to плана на путь к ADR.
   3. Установите status: converged.
   4. Опционально переместите в .apothem/plans/_archive/.
4. Заброшенность — направление заброшено; status: abandoned; архивируйте или, с явным структурированным запросом, отбросьте.
5. Замена — когда новый план заменяет более старый, установите supersedes нового плана на путь старого плана и установите status старого плана соответствующим образом.

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

5. Протокол миграции — однократно, из директории планов harness в .apothem/plans/ каждого проекта

Примечание. Этот протокол применяется к нижестоящим проектам, впервые принимающим дисциплину планов, где предыдущие артефакты планирования находятся внутри директории конфигурации harness (например, ~/.claude/plans/, ~/.claude/.plans/ или эквивалентного пути для другого harness). Рекурсивный случай для самой экосистемы решается через gitignore состояния планов, локального для harness, а не физической миграцией его в исходный код.

Инструменты. Для проектов, уже находящихся на устаревшей раскладке — соседнее дерево <project-root>/.plans/ плюс хранилища <project-root>/.apothem/<harness>/{memory,contexts,learning} для каждого harness — команда apothem migrate-workspace сворачивает оба в общую рабочую директорию <project-root>/.apothem/{plans,memory,learning,contexts}. Команда идемпотентна и недеструктивна: она делает резервную копию каждого потребляемого источника, перемещает .plans/ в .apothem/plans/, объединяет-сливает хранилища памяти и контекста для каждого harness, конкатенирует-дедуплицирует сигналы обучения и никогда не перезаписывает конфликтующую запись. Выполните apothem migrate-workspace --dry-run, чтобы сначала предварительно просмотреть перемещения.

Миграция идемпотентна и обратима вплоть до момента удаления директории планов, локальной для harness (после чего резервный tarball ./.audit/plans-backup-<timestamp>.tar.gz предоставляет артефакт для отката). В примерах ниже используется ~/.claude/plans/; подставьте эквивалентный путь для активного harness.

Шаг 1 — Инвентаризация. Каждый файл под директорией планов, локальной для harness, перечисляется и классифицируется как plan-artifact (quarantined).

Шаг 2 — Карта происхождения. Для каждого плана строится запись происхождения с предполагаемым проектом назначения и оценкой уверенности, выведенной из поля project во frontmatter, сигналов сканирования тела (URL репозиториев, имена пакетов, абсолютные пути) и контекстных подсказок.

Шаг 3 — Подтверждение сопоставления. Полная карта представляется оператору как один консолидированный структурированный запрос (или плотно сгруппированная последовательность, когда количество файлов превышает комфортный размер одного запроса). Для каждого плана оператор выбирает среди:

• Confirm (подтвердить) предполагаемый проект назначения.
• Reassign (переназначить) на другой проект (опция представляет известный оператору список проектов).
• Defer (отложить) — переместить в ~/.claude/.audit/orphan-plans/<original-name> для позднейшей сортировки.
• Discard (отбросить) — только с явным, отдельно подтверждённым структурированным запросом (это деструктивно).

Когда уверенность high для многих планов, запрос предлагает аффорданс confirm-all-high-confidence для сжатия числа обращений, по-прежнему выводя каждое отдельное решение в журнал.

Шаг 4 — Подготовка проекта перед перемещением. Для каждого уникального проекта назначения:

1. Проверьте, что корень проекта существует и читаем.
2. Проверьте, что это git-репозиторий (для не-git корней — выведите через канал структурированного запроса, продолжить ли, инициализировать или пропустить).
3. Убедитесь, что <project-root>/.apothem/plans/ существует; создайте с помощью mkdir -p, если нет.
4. Проверьте, что .gitignore проекта содержит каноническую вставку из §6; при отсутствии добавьте её с заголовочным комментарием, отмечающим эту миграцию.
5. Проверьте, что <project-root>/.apothem/plans/ ещё не отслеживается git; если отслеживается (ошибка предыдущего участника), выведите через канал структурированного запроса с опциями untrack-and-keep, untrack-and-remove-from-history, abort.

Шаг 5 — Перемещение. Для каждой подтверждённой пары план → назначение:

1. Вычислите имя файла назначения: если у источника есть frontmatter, нормализуйте по §3; иначе оберните тело frontmatter-ом (status draft, поле project задано, created из mtime, tags [migrated]) и переименуйте в YYYY-MM-DD--<slug>.md.
2. Если в назначении есть коллизия имён, добавьте -imported-<unix-timestamp> и залогируйте переименование.
3. Скопируйте файл (сохранив mtime), проверьте совпадение SHA-256 в назначении, затем удалите источник.
4. Добавьте запись в <project-root>/.apothem/plans/_migration-manifest.md (также в gitignore), фиксируя: исходный путь, локальный для harness, путь назначения, исходный SHA-256, временную метку, ответ структурированного запроса, авторизовавший это перемещение.

Шаг 6 — Проверка. После всех перемещений:

1. Подтвердите, что директория планов, локальная для harness, пуста (сиротские планы, если есть, находятся внутри директории аудита/карантина этого harness, вне директории, которая вскоре будет удалена).
2. Подтвердите, что у каждого проекта назначения есть заполненная .apothem/plans/ и манифест.
3. Выборочно проверьте по SHA-256, что мигрированное содержимое совпадает с оригиналами.

Шаг 7 — Tarball и удаление. Создайте ./.audit/plans-backup-<ISO-timestamp>.tar.gz, содержащий всё дерево планов, локальное для harness, до перемещения (извлечённое из временного снимка, сделанного на Шаге 1). Затем, через финальный структурированный запрос, подтверждающий готовность, удалите теперь уже пустую директорию планов, локальную для harness.

Шаг 8 — Запись аудита. Выпустите ./.audit/plans-migration.md, резюмирующий каждое перемещение, каждый отложенный файл, каждое отбрасывание, каждое переименование при коллизии и каждое добавление в gitignore.

6. Вставка .gitignore для нижестоящих (каноническая, копировать-вставить)

Каждый проект, принимающий эту экосистему, ДОЛЖЕН добавить следующий блок в свой .gitignore:

# Apothem working directory (project-local shared state: plans, memory,
# learning, contexts; gitignored — never committed). The sole canonical plans
# home is `.apothem/plans/`.
# See: <repo-url>/blob/main/site/content/docs/reference/plans-discipline.mdx
# Ignore the CONTENTS of this directory (not the directory) so the
# `.keep` negation below can take effect.
.apothem/*
!.apothem/.keep

Опциональное исключение .keep сохраняет существование директории в инструментах, которые удаляют пустые пути, не пропуская содержимое. Включать ли .keep, решается для каждого проекта через канал структурированного запроса при первом вызове /plan. Строки .apothem/* + !.apothem/.keep — это каноническая вставка; проект, который всё ещё несёт устаревшее дерево <project-root>/.plans/, выполняет apothem migrate-workspace (§5), чтобы обновить его до .apothem/plans/.

7. Механизмы самопринуждения

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

1. AGENTS.md и зеркальные поверхности инструкций — верхнеуровневый обязательный блок поведения, гласящий: «Артефакты планирования записываются в <project-root>/.apothem/plans/ — единственный канонический дом планов (устаревшее дерево <project-root>/.plans/ обновляется через apothem migrate-workspace) — никогда — ни в какую директорию конфигурации harness (например, ~/.codex/ или ~/.claude/) и никогда — в глобальное расположение. Это правило не подлежит обсуждению; цитируйте §3 спецификации проекта при каждом связанном решении.» Этот блок обнаруживается валидатором plans-discipline-language.
2. Внутрирепозиторный файл инструкций для каждого harness — зеркалит ту же директиву в формулировке, подходящей для поверхности инструкций этого harness (§4 Дисциплина планов); обнаруживается тем же валидатором на каждой зарегистрированной поверхности harness.
3. Стиль вывода по умолчанию — когда ответ произвёл бы содержимое в форме плана (многошаговая стратегия, декомпозиция, разбор дизайна, журнал отладки), стиль направляет артефакт в проектно-локальную запись .apothem/plans/, а не печатает-и-отбрасывает встроенно. Стиль явно инструктирует: «Если корень проекта не обнаруживается, остановитесь со структурированным запросом, спрашивающим оператора, где планировать.»
4. Каждый промпт делегированного исполнителя — несёт строфу Output Surface, называющую .apothem/plans/ назначением для любого артефакта планирования, и строфу Anti-Pattern, называющую директории планов, локальные для harness, запрещёнными.
5. Выделенная слеш-команда /plan — принимает slug + тело, записывает в <project-root>/.apothem/plans/YYYY-MM-DD--<slug>.md с корректным frontmatter, обеспечивает корректность .gitignore назначения, отказывается записывать в пути корня конфигурации harness.
6. Хук pre-tool-use — plan-write-guard — перехватывает каждый вызов инструмента записи файла. Если целевой путь совпадает с расположением плана, локальным для harness (например, ~/.claude/plans/... или ~/.codex/.plans/...), или любым другим глобальным путём экосистемы, который эвристика идентифицирует как имеющий форму плана, хук блокирует запись и поднимает структурированный запрос, предлагающий перенаправление в .plans/ текущего проекта.
7. Валидаторы CI — no-global-plans проваливает сборку, если закоммиченная рабочая память планов вновь появляется в опубликованном дереве; plans-discipline-language проваливается, если каноническая директива выпадает из любого зарегистрированного файла инструкций harness или стиля вывода по умолчанию. Канонические целевые поверхности валидатора (сохранённые как контракты файловой системы) перечислены в блоке ниже.

AGENTS.md
CLAUDE.md
.github/copilot-instructions.md

8. Pre-commit хуки — зеркалят вышеперечисленное локально, так что дисциплина принуждается до того, как любой коммит приземлится.

8. Антипаттерны (категориально запрещены)

• Запись планов внутри директории конфигурации harness (например, ~/.claude/plans/ или ~/.codex/.plans/) или любого другого глобального расположения.
• Коммит планов в git-историю проекта (хуки на момент коммита должны отклонять это).
• Смешивание планов с ADR (разные жизненные циклы, разные расположения, разный статус коммита).
• Планы без frontmatter, планы без имён файлов с датовым префиксом, планы без поля project.
• Межпроектные планы (один план, два проекта). Разделите их — один план на проект.
• Совместное использование планов между машинами через синхронизацию конфигурации harness (например, ~/.claude для Claude Code) — структурный аргумент в пользу сохранения планов проектно-локальными: репозиторий проекта и есть механизм синхронизации в тех редких случаях, когда планы заслуживают совместного использования — и сама эта заслуженность является сигналом, что содержимое следует повысить до ADR.
• Содержимое плана, встроенное внутрь промптов делегированных исполнителей, тел навыков или стилей вывода. Эти поверхности — долговечная поведенческая конфигурация; планы — преходящая рабочая память.
• Применение SPDX-строки заголовка авторства к файлу плана (планы освобождены по замыслу — §2, site/content/docs/reference/authorship-header.mdx §Список исключений).

См. также

• ADR-0001 — архитектурное обоснование, рассмотренные альтернативы, принятые компромиссы.
• site/content/docs/reference/authorship-header.mdx — дисциплина SPDX-строки заголовка авторства (планы категориально освобождены).
• Страница соглашений harness — мультиповерхностные соглашения harness (дисциплина планов появляется как общее утверждение во всех зарегистрированных файлах инструкций harness и каждой опциональной поверхности с подключением). Путь:

site/content/docs/reference/ai-conventions.mdx

• Спецификация проекта §3 — полный канонический текст, зеркалированный здесь.