03. Носитель: VCS — git¶

Конкретная реализация RENAR на git. Структура .req репозитория, submodule-pinning между .req и .src, PR/MR ревью workflow, pre-commit hooks для capability V1-V6, delta-ТЗ workflow. Этот guide — informative; нормативное содержание (capability требования, schemas, lifecycle) — в standard/. Альтернатива на document-oriented store — guide/04-document-store-substrate.

Предпосылки: standard/03-substrate-versioning (нормативные capability V1-V6), reference/02-schemas (frontmatter schemas).

1. Когда выбрать git как носитель¶

Git — носитель по умолчанию для: - Открытых стандартов и проектов (нет зависимости от внутренней инфры). - Внешних клиентов без выделенной document-store инфраструктуры. - Команд с устоявшимся PR-workflow. - Проектов, где требования и код в одной экосистеме (один и тот же VCS provider).

Git не оптимален, если: - Нужны частые конкурентные правки одного артефакта несколькими авторами без merge conflicts. - Нужен built-in полнотекстовый поиск без внешних инструментов. - Требуется UI для non-technical stakeholder (PM, юристов) без git CLI.

В таких случаях рассмотрите document-oriented store — guide/04.

2. Layout двух репозиториев¶

Каноническая структура — два связанных репо.

<project>/
├── <project>.req/                ← репозиторий ТРЕБОВАНИЙ (отдельный VCS repo)
│   ├── tz/                       ← TZ-YYYY-NNN.md (immutable после регистрации)
│   ├── adapt/                    ← ADAPT-NN.md (bridge artefacts)
│   ├── br/                       ← BR-NN.md
│   ├── sr/                       ← SR-NN.md
│   ├── specs/                    ← SPEC-* по подпапкам (arch/, api/, data/, int/, …)
│   │   ├── arch/  api/  data/  ui/  ai/  int/  proc/  sec/  ops/
│   ├── tr/                       ← TR-NN.md (task requirements)
│   ├── tests/                    ← TC-NN.md (контрольные примеры, `TC` — самостоятельные артефакты)
│   ├── dpia/                     ← DPIA-NN.md (опционально для regulated)
│   ├── library/                  ← templates, patterns
│   ├── docs/                     ← AI-generated документация
│   ├── COVERAGE.md               ← auto-generated (`[coverage]` commits)
│   ├── REQUIREMENTS.md           ← auto-generated index
│   └── TEST-PLAN.md              ← auto-generated
└── <project>.src/                ← репозиторий РЕАЛИЗАЦИИ
    ├── src/                      ← код
    ├── tests/                    ← реализации TC (адресуются `automation.location`)
    ├── requirements/             ← submodule → <project>.req @ <commit>
    ├── .gitmodules
    └── README.md

В <project>.req/.gitattributes для bot-generated артефактов:

COVERAGE.md      linguist-generated=true
REQUIREMENTS.md  linguist-generated=true
TEST-PLAN.md     linguist-generated=true
docs/**          linguist-generated=true

Это исключает их из статистики кода и сильно сжимает PR diff.

3. Capability mapping V1-V6 на git¶

Возможность (standard/03 §3.3)	Норматив	Git-механизм
V1 — неизменяемая история	Прошлые состояния артефактов нельзя переписать задним числом	Неизменяемая история коммитов; protected branch + запрет force-push на `main`; `id:` во frontmatter стабилен
V2 — атомарная единица изменения	Изменение применяется целиком либо не применяется	Атомарный commit / squash-merge PR как одна единица; delta-ADAPT = один PR
V3 — сравнение различий и рецензирование	Предложенное изменение рецензируется до утверждения	`git diff` + PR/MR review с обязательным approve до merge
V4 — ветвление / набор изменений	Черновик отделён от утверждённой правды	Feature-ветки (`draft` / `review`) против `main` (`approved`); PR — набор изменений
V5 — сквозная фиксация версии	Реализация ссылается на конкретную версию требования	Submodule-pin между `.req` и `.src`; commit SHA / `requirement-version` в `verifies[]`
V6 — автор и отметка времени	Каждая единица изменения регистрирует автора и время	Метаданные коммита: автор + дата; для AI-агента — `ai-provenance`

RENAR-проверки на git (валидация схемы, контроль переходов статусов, coverage-отчёты, целостность ссылок, reconciliation / drift detection) — это enforcement-механизмы поверх возможностей, а не сами V1–V6. Их раскладка по pre-commit / CI — §3.1 и §8 этого гайда; нормативные классы дрейфа — standard/04 §4.11.

Состояние сценариев. Приведённые ниже механизмы под git — целевой образец v1.0. Фактически готов только scripts/validate-frontmatter.js; остальные (validate-lifecycle, validate-references, generate-coverage, detect-drift и др.) — в бэклоге фазы 8 (раздел §8 этого гайда). Пока скриптов нет, перечисленные возможности обеспечиваются вручную и код-ревью; автоматическое навязывание уровней RENAR-3+ «из коробки» под git пока недостижимо. Замечание относится и к document-store (guide/04).

4. Submodule pinning¶

<project>.src фиксирует конкретный commit <project>.req через git submodule.

4.1 Как работает¶

В <project>.src директория requirements/ — submodule на <project>.req.
При сборке / CI код знает: «я реализую требования по состоянию на commit abc1234».
Разработчик в задаче открывает requirements/sr/SR-05.md через обычный cat или IDE — это файл в worktree.

4.2 Bump pattern¶

При обновлении требований: 1. PR в <project>.req с изменениями требований → ревью → merge. 2. Отдельный PR в <project>.src, который только двигает submodule pointer:

cd requirements
git pull origin main
cd ..
git add requirements
git commit -m "bump requirements: TZ-2026-042 delta + 3 new SR"

3. Этот PR явно показывает: «требования обновились до коммита X».

4.3 Почему submodule, не subtree / monorepo¶

Provenance: для любого коммита кода точно известно, какую версию требований он реализовывал.
Изоляция ревью: ревью требований (в .req) и ревью кода (в .src) не смешиваются.
Атомарность delta-ТЗ: delta — это атомарный PR в .req + последующий submodule-bump в .src. Нет «частично применённой delta».
Совместимость с document store: при переходе на document-oriented store submodule pinning превращается в revision-token pinning — концепция та же.

Альтернативы (subtree, monorepo): рассматривайте только если submodule не работает по причинам, специфичным для вашего VCS provider; во всех остальных случаях submodule — рекомендация.

5. PR/MR review workflow¶

Два уровня ревью, разделённые по репозиториям.

5.1 Ревью в `<project>.req`¶

Фокус рецензента: - Frontmatter schema-valid. - Citation на ТЗ / ADAPT присутствует и валиден. - parent / verified-by / constrained-by ссылки существуют. - Lifecycle transition легитимна. - Source citation в body для каждого нормативного утверждения (на RENAR-4+). - Adversarial AI-review prompt пройден (на RENAR-5).

Утверждение = QG-0 (standard/10 §10.3.1).

5.2 Ревью в `<project>.src`¶

Фокус рецензента: - Submodule pointer соответствует merged commit в .req. - Реализация ссылается на актуальные SR / SPEC через verifies[].version. - Новые / изменённые TC соответствуют контракту в .req. - Никаких изменений Pass/Fail-критериев TC без [test-spec-change] тега.

Утверждение = QG-2 (standard/10 §10.3.3) — после прохождения автоматизированных TC.

5.3 Запрещённые анти-паттерны¶

PR одновременно в .req и .src — нарушает изоляцию ревью; запрещён hook носителя.
Изменение submodule pointer без merged commit в .req — pointer указывает в untracked commit; CI блокирует.
[test-spec-change] без отдельного approval — Pass/Fail-критерий TC изменён вместе с code-fix; CI блокирует merge.

6. Pre-commit и pre-merge hooks¶

Минимальный набор hooks носителя для RENAR-3+ на git.

6.1 Pre-commit (в `<project>.req`)¶

# Запускается на коммит в .req
# Capability V2: schema validation
yamllint --strict $(git diff --cached --name-only | grep '\.md$')
node scripts/validate-frontmatter.js $(git diff --cached --name-only --diff-filter=AM)

# Capability V3: legal lifecycle transitions
node scripts/validate-lifecycle.js $(git diff --cached --name-only --diff-filter=M)

# Capability V5: reference integrity (быстрая проверка только изменённых)
node scripts/validate-references.js --changed-only $(git diff --cached --name-only)

6.2 Pre-merge (CI job в `<project>.req`)¶

Полные проверки, которые медленны для pre-commit:

- name: Full reference validation (V5)
  run: node scripts/validate-references.js --all

- name: Coverage report regeneration (V4)
  run: node scripts/generate-coverage.js
  # commits as [coverage] bot user

- name: Drift detection (reconciliation, weekly)
  run: node scripts/detect-drift.js
  if: github.event.schedule == '0 0 * * 0'

6.3 Pre-merge (CI job в `<project>.src`)¶

- name: Submodule points to merged commit
  run: |
    cd requirements
    git fetch origin
    git merge-base --is-ancestor HEAD origin/main

- name: TC versions pinned to current requirement-version
  run: node scripts/validate-tc-version-pinning.js

- name: No Pass/Fail change without [test-spec-change]
  run: node scripts/validate-test-spec-changes.js

7. ТЗ workflow на git¶

7.1 Forward-workflow (проект с нуля)¶

Первичное создание оси требований из нового ТЗ:

branch в .req: git checkout -b init/TZ-2026-001 в <project>.req.
Регистрация ТЗ: tz/TZ-2026-001.md (immutable после регистрации; зафиксировать подпись клиента и дату).
Создание ADAPT: adapt/ADAPT-001.md — Forward (интерпретация по каждому § ТЗ) + Backward (вопросы клиенту), standard/07. Backward отрабатывается с клиентом до approval.
Двойная подпись ADAPT → QG-ADAPT-approve: ADAPT в approved (клиент + архитектор), open-questions-count == 0.
Декомпозиция: AI-агент выводит BR из approved ADAPT, затем SR (source.adapt), SPEC (constrained-by[]) и парные pos/neg TC.
QG-0 approval каждого артефакта (draft → approved); CI dry-run новых TC.
PR в .req → merge; bot regenerates REQUIREMENTS.md / COVERAGE.md / TEST-PLAN.md.
Setup .src: добавить submodule requirements/ → <project>.req @ <commit>, создать TR, реализовать, QG-2.

7.2 Delta-ТЗ workflow¶

Полная последовательность для применения нового delta-ТЗ.

branch в .req: git checkout -b change/TZ-2026-042 в <project>.req.
Создание delta-ТЗ + delta-ADAPT: tz/TZ-2026-042-delta.md (текст delta) и adapt/ADAPT-NNN-delta.md (forward интерпретация + backward findings, standard/07 §7.6). Delta-ADAPT обязан пройти двойную подпись прежде чем затронутые требования будут модифицированы.
Impact analysis: AI-агент находит затронутые BR / SR / SPEC / TC; помечает TC как obsolete-pending.
Update artefacts: AI-агент обновляет / создаёт BR / SR / SPEC и парные TC (pos+neg) в той же ветке.
Adversarial critic review: на RENAR-5 — обязательно (другая AI-модель).
CI dry-run: новые TC должны запускаться без ошибок инфры.
Finalize: version++, status: approved, regenerate REQUIREMENTS.md / COVERAGE.md / TEST-PLAN.md (bot).
PR в .req → QG-0 approval → merge.
branch в .src: git checkout -b change/TZ-2026-042 в <project>.src.
Bump submodule: cd requirements && git pull && cd ...
Create TR / tasks: для новых / изменённых SR (через /task или специфичный для носителя tooling).
PR в .src «bump requirements + tests + new tasks» → ревью → merge.
Development: взять TR → реализовать → CI → бот заполняет last-run в TC.
QG-2: при зелёных TC — утверждение → AI-агент переводит требование в verified.

Каждый шаг кроме (1) и (9) автоматизирован нативно для носителя через скрипты или CI.

8. Migration notes: scripts/ модернизация¶

Существующие scripts/ — bash + node helpers из ранней эпохи проекта. Состояние модернизации на v1.0-draft:

✅ Legacy terms вычищены. req-branch.sh, req-finalize.sh, req-ai-instructions.md, req-use-template.sh больше не используют устаревшие INT-SR, AIC, UIC, tech-specs, ai-concepts, ui-concepts. Closed list актуальных типов — standard/04 §4.4 (BR/SR/TR + 9 SPEC). Остаточные упоминания в reference/01-glossary.md и reference/02-schemas.md являются legacy-mapping для проектов, мигрирующих с предыдущих версий.
✅ Schema validator создан. scripts/validate-frontmatter.js — Node ES-module, проверяет frontmatter всех .md в standard/, guide/, reference/, core/: required fields title / order / lang ∈ {ru, en}. Запуск: node scripts/validate-frontmatter.js [--quiet]; exit 0 если все валидны, exit 1 при первой ошибке. Источник схемы — reference/02-schemas.
⏳ ADAPT в forward-workflow. Начальное создание (ТЗ → ADAPT → BR) сейчас не задокументировано как отдельный workflow рядом с §7 (delta-workflow); шаг 2 в §7 явно использует delta-ADAPT согласно standard/07 §7.6. Утверждённый forward-workflow — задача отдельного draft главы.
⏳ Pre-commit hooks (§6.1) пока частично разбросаны по req-finalize.sh. Целевое состояние — выделить в отдельные scripts/validate-*.js; validate-frontmatter.js — первый такой модуль.

Глава описывает целевой набор скриптов на выпуске v1.0; строки без отметки ✅ — работа для фазы 8 (продолжение бэклога).

9. Common operations¶

Шорткаты для частых операций.

Операция	Команда
Найти SR по ID	`grep -r "^id: SR-12" sr/`
Найти TC, верифицирующий SR-12	`grep -rl "id: SR-12" tc/`
Найти orphan SR (без TC)	`node scripts/find-orphans.js sr`
Создать новый SR из шаблона	`cp library/templates/sr.md sr/SR-NN.md && $EDITOR sr/SR-NN.md`
Diff frontmatter за период	`git log --all --since=... -- sr/`
Текущая requirement-version SR-12	`yq '.version' sr/SR-12.md`
Список stale TC (last-run < current version)	`node scripts/list-stale-tc.js`

10. CI/CD integration patterns¶

10.1 Bot-commit conventions¶

Auto-generated артефакты коммитятся hooks носителя с conventional commit-message тегами для машинного парсинга:

Тег	Когда	Что коммитится
`[coverage]`	Post-merge в `.req`	Регенерация COVERAGE.md / REQUIREMENTS.md / TEST-PLAN.md
`[baseline-update]`	После approval PR с изменением эталона	Перегенерация PNG-эталонов для SPEC-UI
`[bump-req]`	Submodule bump в `.src`	Только submodule pointer + minimal metadata
`[reconcile]`	Reconciliation hook находит drift	Авто-fix очевидных рассогласований; flag для остальных
`[test-spec-change]`	Pass/Fail-критерий TC изменён	Manual; требует отдельный approval от reviewer

Hook носителя парсит commit message и применяет различные validation rules в зависимости от тега. [coverage] / [bump-req] / [reconcile] коммиты — от bot user; [baseline-update] / [test-spec-change] — от human + bot signature.

10.2 Bot-user setup¶

Отдельный bot account (например renar-bot@<org>) с write permission в <project>.req и <project>.src.
Bot commits signed (GPG / SSH commit signature).
Bot user не может approve PR (separation of duties — утверждение всегда human).

10.3 branch protection¶

В обоих репо: - main (или master) — protected. Push требует merged PR. - Required status checks: schema validation (V2), reference integrity (V5), lifecycle validation (V3). - Reviewers required: ≥ 1 для большинства; ≥ 2 для priority=must BR / SR / SPEC.

11. Перекрёстные ссылки¶

standard/03-substrate-versioning — нормативные требования к носителю (capability V1-V6).
reference/02-schemas — frontmatter schemas для validation hooks.
02-transition-guide — где этот guide вписывается в путь от pre-RENAR к RENAR-N.
04-document-store-substrate — informative обзор document-oriented store (альтернатива git).
07-failure-modes — что может пойти не так на git как носителе (схема обхода hooks, etc.).
standard/10-lifecycle-qg — нормативные lifecycle переходы, которые validate-lifecycle hook должен enforce.

12. Open questions¶

Стандартизировать ли минимальные реализации перехватов как единое спецификационное описание, на которое опираются и VCS, и document store?
Submodule vs subtree: какие conditions делают subtree приемлемой альтернативой? Сейчас гайд однозначно за submodule.
[coverage] bot user: best practice для signing / permission в multi-org проектах?
Периодичность детекции дрейфа: weekly — хороший вариант по умолчанию, но что для high-velocity teams (> 50 PR/неделя)?