07. ADAPT — двусторонняя адаптация ТЗ

Часть RENAR Standard v1.0-draft · ← Оглавление

7.1 Назначение главы

Глава нормирует ADAPT — обязательный артефакт жизненного цикла RENAR, расположенный между immutable ТЗ (договорным документом) и инженерными требованиями BR/SR/SPEC. ADAPT обеспечивает двустороннюю адаптацию: forward (инженерная интерпретация ТЗ для клиента) + backward (вопросы, противоречия, гэпы — от инженера клиенту с lifecycle ответов).

ADAPT — следствие Утверждения 2 из §5.4 (RENAR — waterfall-form ≠ classical waterfall, потому что ADAPT обеспечивает bidirectional adaptation вместо «throw over the wall»).

7.2 Проблема, которую нормирует ADAPT

Без формализованного промежуточного артефакта между ТЗ и BR/SR возникает один из двух негативных исходов:

Исход	Что происходит
Drift ТЗ	ТЗ редактируется после подписания → нарушается договор
Скрытая интерпретация	Инженерные предположения молча просачиваются в BR/SR/SPEC → разрушается trace chain и provenance

ADAPT исключает оба исхода: ТЗ остаётся immutable договорным документом, все интерпретации, уточнения и backward findings регистрируются в ADAPT, который сам становится immutable после двойной подписи (§7.5).

7.3 Цикл двусторонней адаптации

        ┌───────────────────────────────┐
        │   ТЗ (immutable, договор)     │
        └───────────────┬───────────────┘
                        │ источник
                        ▼
┌──────────────────────────────────────────────┐
│              ADAPT-NNN                       │
│                                              │
│  Forward (инженер → клиент)                  │
│  ─ интерпретация по разделам ТЗ              │
│  ─ term mapping                              │
│  ─ достроенные сценарии                      │
│  ─ scope clarification                       │
│                                              │
│  Backward (инженер → клиент)                 │
│  ─ 7 категорий findings                      │
│  ─ lifecycle: open → asked → answered →      │
│              resolved → frozen               │
│                                              │
│  Status: draft → review → client-ready →     │
│         answered → approved → frozen         │
│  Approval: двойная подпись клиент+архитектор │
└────────────────────┬─────────────────────────┘
                     │ approved
                     ▼
        ┌───────────────────────────────┐
        │   BR / SR / SPEC              │
        │   ссылаются на ADAPT§         │
        │   через source.adapt          │
        └───────────────────────────────┘

ТЗ — первоисточник; ADAPT — canonical источник интерпретации; BR/SR/SPEC ссылаются на ADAPT, а не на ТЗ напрямую.

7.4 Нормативные требования к ADAPT

7.4.1 Обязательность

Каждое ТЗ обязано иметь ровно один корневой ADAPT (ADAPT-NNN). При наличии delta-ТЗ — каждый delta-ТЗ обязан иметь свой delta-ADAPT (§7.6).

Производство BR / SR / SPEC из ТЗ без прохождения через approved ADAPT — нарушение стандарта. Hooks lifecycle (глава 10) обязаны блокировать создание BR / SR / SPEC, ссылающегося на ADAPT в статусе ниже approved.

7.4.2 Immutability ТЗ

ТЗ — договорной документ. После регистрации ТЗ в substrate его содержимое не редактируется. Если в ходе работы выясняется, что в ТЗ ошибка / пропуск / противоречие — это регистрируется как backward finding в ADAPT (§7.4.4), клиент даёт ответ, ответ становится частью ADAPT. ТЗ остаётся immutable.

При большом количестве правок или при изменении scope — клиент подписывает delta-ТЗ как новый immutable документ (§7.6).

7.4.3 Forward adaptation

Forward раздел ADAPT для каждого раздела ТЗ обязан содержать:

Элемент	Обязательность	Цель
Точная ссылка на ТЗ§N.N	mandatory	Provenance
Цитата из ТЗ (или paraphrase с явной пометкой)	mandatory	Контекст
Инженерная интерпретация раздела	mandatory	Перевод языка клиента → язык требований
Term mapping (клиент → инженер)	mandatory если применимо	Дезамбигуация терминов
Достроенные сценарии	mandatory если ТЗ их подразумевает	Явная фиксация implicit cases
Scope clarification (входит / не входит)	mandatory	Граница работ
Forward links на BR/SR/SPEC	auto-derived	Trace chain (§7.7)

7.4.4 Backward adaptation

Backward раздел ADAPT фиксирует обнаруженные проблемы по семи нормативным категориям. Список категорий закрыт на v1.0; добавление новых категорий — через formal change procedure стандарта (см. глава 14).

ID	Категория	Что регистрируется
`contradiction`	Противоречие	Внутренние противоречия в ТЗ (§A vs §B)
`gap`	Пропуск	ТЗ молчит о том, без чего невозможна реализация
`hidden-assumption`	Скрытое предположение	Предположение инженера, которое может быть неверно
`feasibility`	Реализуемость	Технически нереализуемое или непропорционально дорогое требование
`regulatory`	Регуляторика	Требование, затрагивающее законодательство / compliance
`terminology`	Терминология	Неясный термин ТЗ с несколькими возможными значениями
`scope`	Скоп	Неясная граница работ

Каждая backward запись имеет stable ID (B-NNN), immutable после создания. ID не переиспользуется даже для отозванных записей (audit trail).

7.4.5 Lifecycle одной backward записи

open → asked-to-client → answered → resolved → frozen
              ↑                          │
              └────── revised ───────────┘  (если ответ требует уточнения)

Статус	Что значит
`open`	Инженер записал; не отправлено клиенту
`asked-to-client`	Вопрос отправлен клиенту, ожидается ответ; зафиксирована дата
`answered`	Клиент ответил; ответ записан в документ с author + timestamp (V6 substrate capability)
`resolved`	Инженер интегрировал ответ в forward интерпретацию
`revised`	Ответ клиента расплывчатый; повторный вопрос. Переход обратно в `asked-to-client`
`frozen`	После approval ADAPT — изменения невозможны

Approval ADAPT (§7.5) запрещён при наличии хотя бы одной backward записи в статусе open / asked-to-client / answered / revised. Все backward записи обязаны быть в resolved перед approval.

7.5 Approval ADAPT — двойная подпись

ADAPT переходит из статуса answered в approved только после двойной подписи (atomic change unit, V2 + V3 substrate capabilities из §11.3):

Подпись	Кто	Что подтверждает
Client signature	Клиент или представитель клиента с полномочиями	Forward интерпретация совпадает с тем, что заказчик имел в виду; ответы на backward вопросы — финальные
Architect signature	Архитектор со стороны исполнителя	Все backward findings отработаны (нет нерешённых); forward интерпретация технически реализуема

Substrate-нативная реализация подписи — комбинация V3 (diff & review) + V6 (author + timestamp). Конкретный механизм (digital signature / approval workflow / двойная review-аттестация) выбирается имплементацией и фиксируется в conformance manifest (§11.7).

После approval ADAPT immutable наравне с ТЗ. Дальнейшие изменения — только через delta-ADAPT (§7.6) или errata (§7.6.3).

7.6 Delta-ТЗ и delta-ADAPT

7.6.1 Workflow

При появлении delta-ТЗ от клиента:

Клиент регистрирует delta-ТЗ в substrate как новый immutable документ (TZ-YYYY-NNN-delta-N).
Клиент подписывает delta-ТЗ (V6 author + timestamp).
Архитектор / AI-агент создаёт delta-ADAPT (ADAPT-NNN-delta-N) с frontmatter полем parent-adapt: ADAPT-NNN и source-tz: TZ-YYYY-NNN-delta-N.
Forward раздел delta-ADAPT покрывает только разделы delta-ТЗ (не дублирует основной ADAPT).
Backward раздел delta-ADAPT фиксирует findings конкретно по delta-ТЗ.
Approval delta-ADAPT — двойная подпись (§7.5).
Из approved delta-ADAPT — дельта в BR / SR / SPEC (новые / обновлённые / deprecated).

7.6.2 Цепочка delta-ADAPT

ADAPT-001 (от TZ-YYYY-NNN main)
  └─ ADAPT-001-delta-1 (от TZ-YYYY-NNN-delta-1)
        └─ ADAPT-001-delta-2 (от TZ-YYYY-NNN-delta-2)
              └─ ADAPT-001-delta-3 (от TZ-YYYY-NNN-delta-3)

Цепочка строго последовательна: применение delta-ADAPT обязано идти по порядку (см. V5 cross-substrate version pin в §11.3.5). Перенумеровать или переставлять delta-ADAPT в цепочке запрещено.

7.6.3 Errata для уже approved ADAPT

Если через продолжительное время после approval обнаруживается, что в ADAPT-NNN неверная forward интерпретация или некорректный resolved backward — два допустимых исхода:

Исход	Артефакт
ТЗ содержит ambiguity, обнаруженную поздно	delta-ADAPT с новой backward записью и ответом клиента
Inсorrectly interpreted (ошибка инженера)	errata-ADAPT-NNN-M как отдельный артефакт с подписью клиента (если меняет contractual outcome) или только архитектора (если cosmetic)

В обоих исходах frozen ADAPT не редактируется. Только добавление новых артефактов с явной типизированной связью.

7.7 Связь ADAPT с другими артефактами

7.7.1 BR / SR / SPEC ссылаются на ADAPT через `source.adapt`

# Frontmatter SR (пример)
source:
  adapt: ADAPT-001
  adapt-section: "Forward §3"   # forward интерпретация — canonical источник
  tz-section: "§3.4"            # для traceability; первоисточник остаётся ТЗ

Поле source.adapt — нормативно обязательное для BR, SR, SPEC. Поле source.tz-section — рекомендуемое (для двойной trace chain).

7.7.2 Полная trace chain

TC-NN  →  verifies SR-12  →  derived from ADAPT-001 §3 (forward)
                                  │     │
                                  │     └─ resolves B-007 (was: contradiction,
                                  │            answered by client 2026-03-15)
                                  │
                                  └─ interprets TZ-YYYY-NNN §3.4

При audit от тест-кейса можно дойти до: (a) исходного раздела ТЗ, (b) интерпретации этого раздела, (c) backward вопросов инженера, (d) ответов клиента, (e) производных BR / SR / SPEC.

7.7.3 TR не ссылается на ADAPT напрямую

TR (задача) ссылается на SR / SPEC, а они уже ссылаются на ADAPT. Исполнитель задачи не обращается к ADAPT напрямую — все нужные интерпретации уже содержатся в SR / SPEC. Если исполнитель обнаружил неясность в SR — это сигнал либо для backward finding в ADAPT (если корень в ТЗ), либо для уточнения SR (если корень в декомпозиции).

7.8 ADAPT schema

7.8.1 Frontmatter (обязательные поля)

---
id: ADAPT-NNN                       # immutable; NNN sequential per project
title: "Адаптация ТЗ <name>"
type: ADAPT

source-tz:
  id: TZ-YYYY-NNN
  signed-date: "<ISO-date>"
  signed-by-client: "<name + role>"
  document-version-ref: "<substrate-native version identifier>"   # V5 pin (см. §11.3.5)

parent-adapt:                       # для delta-ADAPT
  id: ADAPT-NNN
  delta-tz: TZ-YYYY-NNN-delta-N

status: draft | review | client-ready | answered | approved | frozen | obsolete
created: "<ISO-date>"
last-updated: "<ISO-date>"

approval:                            # обязательно для approved
  client-signature:
    signed-by: "<name>"
    role: "<role>"
    organization: "<client-org>"
    signed-at: "<ISO-datetime>"      # V6 timestamp
    signature-ref: "<substrate-native reference>"
  architect-signature:
    signed-by: "<name>"
    role: architect
    signed-at: "<ISO-datetime>"

generates-requirements: []           # auto-derived; BR/SR из этого ADAPT
generates-specs: []                  # auto-derived; SPEC-* из этого ADAPT
open-questions-count: integer        # auto-derived; обязательно 0 для approved
resolved-questions-count: integer

ai-provenance:                       # обязательно если ADAPT draft был AI-сгенерирован
  generated-by: "<vendor>-<model>@<date>"
  prompt-template: "<template-path>@<version>"
  context-tokens: integer
  output-tokens: integer
  human-edits: boolean               # обязательно true для approved — клиент видел текст
---

7.8.2 Body structure (обязательные разделы)

Обязательные разделы тела ADAPT:

Краткое содержание — 3–5 параграфов для одностраничного чтения клиентом.
Term mapping — таблица «клиент → инженер».
Forward — раздел на каждый раздел ТЗ с обязательными элементами из §7.4.3.
Backward findings — все записи с lifecycle из §7.4.5.
Резюме backward findings — статистическая таблица по категориям и статусам.
Generated artifacts — auto-derived список BR / SR / SPEC.
История изменений ADAPT — substrate-native auto-generated.

Опциональные разделы — на усмотрение имплементации, не нормированы.

7.9 Quality Gates ADAPT

ADAPT имеет dedicated state machine. Детали в главе 10 §10.4. Краткая сводка:

Gate	Pre-condition	Post-condition
QG-ADAPT-draft	ADAPT создан; присутствует frontmatter	Forward охватывает все разделы ТЗ
QG-ADAPT-review	Forward complete; первичные backward в `open`	Все backward в `open` или `asked-to-client`
QG-ADAPT-client-ready	Все backward в `asked-to-client`; пакет вопросов сформирован	Готов к отправке клиенту
QG-ADAPT-answered	Все backward в `answered`; resolution начат	Готов к финализации
QG-ADAPT-approve	Все backward в `resolved`; двойная подпись готова	ADAPT immutable; разрешена генерация BR / SR / SPEC
QG-ADAPT-frozen	Approved	Дальнейшие изменения — только через delta-ADAPT или errata

Hooks substrate (§11.3.3 V3, §11.3.5 V5) обязаны:

Блокировать переход в approved при open-questions-count > 0.
Блокировать создание BR / SR / SPEC с source.adapt на ADAPT в статусе ниже approved.
Пересчитывать open-questions-count / resolved-questions-count после каждого изменения.

7.10 ADAPT и AI-генерация

7.10.1 AI-агент создаёт draft ADAPT

При импорте ТЗ AI-агент создаёт draft ADAPT автоматически: forward интерпретация по разделам, попытка обнаружить contradictions / gaps / terminology ambiguities, первая версия term mapping. Этот draft — стартовая точка для архитектора, не финальный артефакт.

7.10.2 Adversarial reviewer

Применение Принципа 2 (Adversarial review) из research/02: отдельный AI-агент-критик с другой моделью ищет, что primary агент пропустил — недостающие backward findings. Если adversarial reviewer находит ≥3 серьёзных new findings — primary draft возвращается на доработку.

7.10.3 Клиент не общается с AI напрямую

Backward вопросы агрегируются архитектором в человеческий формат перед отправкой клиенту. Архитектор может убрать дубликаты, переформулировать на язык клиента, объединить связанные. Клиент видит подготовленный список вопросов, не raw output AI-агента. Ответ клиента (в любой форме: текст, видеозвонок, письмо) транскрибируется архитектором в ADAPT с указанием канала и аутентификации.

7.11 Storage layout

ADAPT-документы хранятся в подпапке adapt/ requirements substrate:

[project]/
  adapt/
    ADAPT-001-main.md
    ADAPT-001-delta-1.md
    ADAPT-001-delta-2.md
    ADAPT-002-main.md
    errata/
      errata-ADAPT-001-1.md
  tz/
    TZ-YYYY-NNN.md
    TZ-YYYY-NNN-delta-1.md

Конкретная файловая структура на конкретном substrate — substrate-specific (см. guide/03 для distributed VCS; guide/04 для document-oriented store).

7.12 Связь с другими главами

Глава	Связь
05 Methodology positioning	ADAPT — следствие Утверждения 2 (bidirectional adaptation вместо «throw over the wall»)
06 Requirements hierarchy	BR / SR ссылаются на ADAPT через `source.adapt`
08 Specifications	SPEC-* также ссылаются на ADAPT через `source.adapt`
09 Test cases	TC через SR / SPEC возвращается в ADAPT для полной trace chain
10 Lifecycle и QG	ADAPT state machine + QG-ADAPT-* gates
11 Substrate versioning	Двойная подпись (V6) + atomic approval (V2 + V3); immutability после approved (V1); delta-ADAPT через V4
14 Conformance	ADAPT для каждого ТЗ — mandatory clause