Tool guide — Git substrate

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

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

1. Когда выбрать git substrate

Git — substrate по умолчанию для:

Открытых стандартов и проектов (нет зависимости от внутренней инфры).
Внешних клиентов на TAUSIK / KAI runtime.
Команд с устоявшимся PR-workflow.
Проектов, где требования и код в одной экосистеме (один и тот же VCS provider).

Git не оптимален, если:

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

В таких случаях — Raven, 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
│   ├── spec/                     ← SPEC-{ARCH,API,DATA,INT,PROC,UI,AI,SEC,OPS}-NN.md
│   ├── tr/                       ← TR-NN.md (task requirements)
│   ├── tc/                       ← TC-NN.md (test cases, first-class)
│   ├── 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

Capability	Норматив	Git-механизм
V1 — Versioned content addressing	Каждый артефакт имеет stable identifier + content hash	git commit SHA + file path; `id:` поле во frontmatter (stable)
V2 — Schema validation	Структура артефактов проверяется автоматически	Pre-commit hook + CI job: `yamllint` + JSON Schema validator против `reference/02-schemas.md`
V3 — Lifecycle state enforcement	Переходы статусов следуют state machine	Pre-commit hook: проверка legal-transition (старый status → новый status) per standard/10-lifecycle-qg
V4 — Reporting / aggregation	Coverage / index / status reports auto-generated	Bot-commit на post-merge: `scripts/generate-coverage.js` + `[coverage]` тег
V5 — Reference integrity	Cross-references между артефактами не «висят»	CI job: парсит `parent`, `verified-by`, `constrained-by`, `verifies` поля; проверяет существование targets
V6 — Drift detection	Дрейф между артефактами и реализацией ловится автоматически	CI job (еженедельно + on-demand): walks frontmatter, проверяет соответствие с кодом, `last-run.requirement-version` ≥ current

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

При обновлении требований:

PR в <project>.req с изменениями требований → ревью → merge.

Отдельный 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"

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

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

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

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

5. PR/MR review workflow

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

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

Reviewer focus:

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

Approval = QG-0 (standard/10 §10.3.1).

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

Reviewer focus:

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

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

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

PR одновременно в .req и .src — нарушает изоляцию ревью; запрещён substrate 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

Минимальный набор substrate 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 (V6, 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. Delta-ТЗ workflow на git

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

Branch в .req: git checkout -b change/TZ-2026-042 в <project>.req.
Создание delta-ТЗ: tz/TZ-2026-042-delta.md (текст delta).
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 или substrate-specific tooling).
PR в .src «bump requirements + tests + new tasks» → ревью → merge.
Development: взять TR → реализовать → CI → бот заполняет last-run в TC.
QG-2: при зелёных TC — approval → AI-агент переводит требование в verified.

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

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

Существующие scripts/ — bash + node helpers из ранней эпохи проекта. Известные обновления, необходимые при переходе на v1.0-draft (отдельная задача, не часть этой главы):

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 9 SPEC типов (standard/03 §3.4).
Workflow не покрывает ADAPT-этап (между ТЗ и BR). Скрипт req-import-tz.sh должен также создавать ADAPT skeleton.
Pre-commit hooks (§6.1) сейчас отсутствуют как отдельные модули — частично разбросаны по req-finalize.sh. Требуется выделить в отдельные scripts/validate-*.js.
Schema validator (validate-frontmatter.js) — отсутствует; нужно создать на основе reference/02-schemas.

Эта модернизация — отдельный task в roadmap (Phase 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 артефакты коммитятся substrate hooks с conventional commit-message тегами для машинного парсинга:

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

Substrate 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 — approval всегда 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. Cross-references

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

12. Open questions

Стандартизировать ли minimum hook implementations как substrate-agnostic spec, на которую git и Raven обе ссылаются?
Submodule vs subtree: какие conditions делают subtree приемлемой альтернативой? Сейчас гайд однозначно за submodule.
[coverage] bot user: best practice для signing / permission в multi-org проектах?
Drift detection cadence: weekly — хороший default, но что для high-velocity teams (> 50 PR/неделя)?