forgeplan supersede

forgeplan supersede выводит из эксплуатации активный артефакт и записывает, что конкретная замена принимает на себя его ответственность. Старый артефакт переходит в состояние superseded (замещённый) - терминальное состояние, из которого он никогда не сможет выйти, - и типизированная ссылка записывается от старого ID к новому. Это канонический способ развития решений в Forgeplan: история сохраняется, обратные ссылки продолжают работать, и любой, кто читает старый артефакт, немедленно направляется к текущему ответу.

Когда использовать

• Вы переписали ADR с новым решением, и более новая версия уже активна (ADR-005 заменяет ADR-003).
• RFC v2 поглощает RFC v1: та же проблема, лучшая архитектура, старый план больше не применим.
• PRD был разделён на два более сфокусированных PRD, и один из них продолжает охватывать первоначальную область.
• Spec был рефакторингован, и старый контракт больше недействителен, но должен оставаться читаемым для истории.

Когда НЕ использовать

• Старый артефакт просто устарел без прямой замены - вместо этого используйте forgeplan deprecate с указанием причины.
• Вы хотите заново изучить проблему и создать черновик преемника с нуля - используйте forgeplan reopen, который автоматически создаёт новый черновик.
• Замещающий артефакт ещё не существует. Сначала создайте и активируйте его, затем заместите.
• Старый артефакт всё ещё находится в состоянии draft (черновик). Черновики не нуждаются в замещении - просто удалите или перепишите их.

Использование

forgeplan supersede --by <BY> <ID>

Аргументы

  <ID>  ID артефакта для замещения

Опции

      --by <BY>  ID замещающего артефакта
  -h, --help     Вывести справку
  -V, --version  Вывести версию

Примеры

Пример 1: Заменить ADR-003 на ADR-005

forgeplan activate ADR-005
forgeplan supersede ADR-003 --by ADR-005

Сначала активируйте преемника, чтобы ссылка на замену указывала на активное решение, затем заместите оригинал.

Пример 2: Переход RFC с v1 на v2

forgeplan supersede RFC-002 --by RFC-014

RFC-002 переходит в состояние superseded (замещённый) (терминальное). Любой, кто переходит по просроченной ссылке на RFC-002, видит указатель --by на RFC-014.

Пример 3: Проверить родословную

forgeplan supersede PRD-007 --by PRD-021
forgeplan links PRD-007

После замещения проверьте граф связей, чтобы убедиться, что ребро superseded_by было записано.

Как это вписывается в рабочий процесс

Supersede - это чистый выход из цикла Shape → Validate → Code → Evidence → Activate для решения, которое должно быть заменено, а не выведено из эксплуатации. Он всегда сочетается с активацией преемника: новый артефакт проходит полный цикл, становится active (активным), и только затем вы запускаете supersede для предшественника. Поскольку состояние является терминальным, убедитесь, что замена действительно является ответом - если вы всё ещё исследуете, используйте reopen.

Распространённые ошибки

Ошибка	Причина	Исправление
--by артефакт не найден	ID замены не существует	Сначала создайте и активируйте преемника
--by артефакт находится в черновике	Преемник ещё не активирован	Запустите forgeplan activate <new-id> перед замещением
Невозможно заместить из черновика	Оригинал всё ещё в черновике	Черновики не нуждаются в замещении - отредактируйте или удалите
Уже в терминальном состоянии	Артефакт уже замещён или отменён	Терминальные состояния окончательны - ничего не делать

См. также

• forgeplan deprecate - вывести из эксплуатации без замены
• forgeplan reopen - отменить и начать новый черновик для переоценки
• forgeplan activate - активировать преемника перед замещением
• forgeplan links - проверить связь superseded_by
• Руководство по жизненному циклу v2
• Методология: Жизненный цикл артефактов