[governance/repo-guard] Схлопнуть и выровнять canonical docs registry PMM

[netkeep80]

Контекст

После введения:

• pmm_target_model.md
• pmm_transformation_rules.md
• разделения docs-consistency и version-consistency
• канонического comment_policy.md

в репозитории остаётся следующий источник расползания контекста:

канонический набор документов описан сразу в нескольких местах.

Сейчас роль «канонических документов» одновременно или частично живёт в:

• docs/index.md
• repo-policy.json -> paths.canonical_docs
• docs/repository_shape.md
• косвенно в CONTRIBUTING.md

Это опасно по нескольким причинам:

• один и тот же документ может считаться canonical в одном месте и не считаться в другом;
• docs review и repo-guard начинают опираться на разные списки истины;
• swarm получает не один центр навигации, а несколько почти-совпадающих;
• любой новый doc может снова незаметно увеличить surface через рассинхрон, а не через осознанное решение.

После policy-issue следующий правильный шаг — не добавлять новые тексты, а схлопнуть registry канонических docs до согласованного состояния.

Цель

Сделать канонический набор документов PMM согласованным, минимальным и однозначным:

• docs/index.md — навигационный canonical index;
• repo-policy.json — enforcement registry;
• между ними нет рассинхрона;
• число документов, считающихся canonical без необходимости, не растёт.

Тип изменения

governance/repo-guard

Архитектурный смысл

Issue не меняет PMM kernel.

Он нужен, чтобы:

• убрать ambiguity вокруг canonical docs;
• сделать docs governance пригодным для swarm-driven development;
• подготовить базу для дальнейшего уменьшения docs surface;
• не допустить нового роста репозитория за счёт «полуканонических» документов.

Разрешённый scope

• docs/index.md
• repo-policy.json
• docs/repository_shape.md
• CONTRIBUTING.md — только если нужна минимальная корректировка ссылки/термина
• при необходимости: scripts/check-docs-consistency.sh — только если нужен минимальный sync с новым canonical registry

Запрещённый scope

• include/**
• tests/**
• single_include/**
• examples/**
• demo/**
• .github/workflows/** — если sync не требует неизбежной минимальной правки
• создание новых .md файлов
• любые generated files

Surface budget

• max_new_files: 0
• max_new_docs: 0
• max_net_added_lines: 30
• docs_surface_delta: non_positive
• generated_surface: must_not_touch

Требуемый результат

Нужно добиться следующего состояния.

1. Один явный навигационный канон

docs/index.md должен быть короткой и понятной точкой входа:

• перечисляет только реально canonical docs;
• не содержит полуисторических или поддерживающих документов как равноправный canon;
• не плодит уровни важности без необходимости.

2. Один enforcement registry

repo-policy.json -> paths.canonical_docs должен:

• содержать тот же canonical set, что и docs/index.md, где это применимо;
• не содержать устаревших или спорных записей;
• не играть роль второго независимого списка истины.

3. Явное разделение классов docs

Нужно чётко различить:

• canonical docs;
• supporting docs;
• archive/history docs;
• governance plumbing docs.

То, что не должно считаться canonical, не должно оставаться в canonical registry только «потому что уже лежит там».

4. Минимизация canon surface

Нужно убрать из канонического слоя всё, что:

• дублирует более сильный документ;
• является вспомогательным, а не нормативным;
• нужно для истории/объяснения, но не для текущего navigation contract.

5. Review semantics

Нужно зафиксировать в самом результате diff, что:

• canonical docs registry стал меньше или как минимум строже;
• docs/index и repo-policy больше не спорят друг с другом;
• новый doc нельзя будет сделать canonical “по инерции” без осознанного изменения обоих слоёв.

Acceptance criteria

Issue считается выполненным, если:

• не создано ни одного нового markdown-файла;
• docs/index.md и repo-policy.json согласованы по canonical docs;
• различие между canonical / supporting / archive docs стало явнее;
• canonical set не расширился без очень жёсткой причины;
• docs surface не вырос;
• code surface и generated surface не затронуты.

Документационный контракт

Разрешено:

• удалить из canonical registry лишние записи;
• переназвать роль существующего документа в docs/index.md;
• сократить поясняющий текст, если он дублирует уже зафиксированный canon.

Запрещено:

• создавать новый governance-doc для описания той же проблемы;
• добавлять новый markdown-index рядом с существующим;
• расширять canonical set “на будущее”;
• оставлять рассинхрон между index и repo-policy как сознательный компромисс.

Non-goals

• не чистить содержимое всех docs подряд;
• не переписывать архитектурные документы PMM;
• не заниматься extraction или kernel refactor;
• не менять comment policy глубже необходимого;
• не переделывать весь repo-guard rollout.

Риски

1. Агент может попытаться просто «синхронизировать всё со всем», не уменьшая canon surface.
2. Может сохраниться слишком широкий список canonical docs, только более аккуратно записанный.
3. Может появиться соблазн завести новый документ для объяснения registry semantics, что нарушит цель issue.
4. Небрежный sync с check-docs-consistency.sh может оставить скрытый рассинхрон между policy и CI.

PR contract

PR по этому issue должен:

• менять только разрешённый scope;
• не создавать новые markdown-файлы;
• явно показать:
  • какой canonical set был до PR;
  • какой canonical set стал после PR;
  • какие записи были переведены из canonical в supporting/archive/governance;
  • net markdown delta;
• подтвердить, что code surface = untouched.

Определение успеха

Успехом считается не просто «подправили docs/index или repo-policy», а то, что после merge:

• у PMM появился один ясный canonical docs registry;
• swarm сложнее будет расширять docs canon случайно;
• docs governance стала строже и компактнее;
• репозиторий стал меньше по смысловой и навигационной поверхности, а не больше.