[docs-comments-cleanup] Схлопнуть и канонизировать политику документации и комментариев PMM

[netkeep80]

Контекст

После фиксации:

• pmm_target_model.md — роли и границ PMM;
• pmm_transformation_rules.md — правил управляемой трансформации;
• разделения docs-consistency и version-consistency;

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

• документы накапливаются быстрее, чем схлопываются;
• правила про комментарии, docs hygiene и governance частично дублируются;
• CONTRIBUTING.md, docs/comment_policy.md и другие тексты рискуют начать пересказывать друг друга;
• у роя агентов нет достаточно жёсткого канонического правила: где должен жить текст и какой текст вообще допустим.

Нужен один короткий канонический policy-layer, который:

• запрещает накопление process-noise;
• фиксирует, какие документы считаются каноническими;
• фиксирует, какие комментарии допустимы;
• требует, чтобы текстовая поверхность PMM сокращалась, а не росла.

Цель

Привести политику документации и комментариев PMM к одному каноническому центру без создания новых markdown-файлов и без роста docs surface.

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

docs-comments-cleanup

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

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

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

• уменьшить текстовую поверхность репозитория;
• убрать дублирование между governance/docs/comment rules;
• зафиксировать правило one concept -> one canonical place;
• сделать дальнейшие docs/comments PR проверяемыми по короткому и жёсткому policy.

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

• docs/comment_policy.md
• CONTRIBUTING.md
• docs/index.md — только если нужна минимальная корректировка навигации
• при необходимости: один существующий governance/doc файл, если нужно убрать явное дублирование

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

• include/**
• tests/**
• single_include/**
• scripts/**
• .github/**
• repo-policy.json
• создание новых .md файлов
• любые изменения generated surface

Surface budget

• max_new_files: 0
• max_new_docs: 0
• max_net_added_lines: 40
• docs_surface_delta: non_positive
• comments_delta: same_or_shrink
• generated_surface: must_not_touch

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

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

1. Один канонический центр правил для текста

docs/comment_policy.md должен стать коротким каноническим документом, который задаёт:

• какие типы комментариев допустимы;
• какие типы документов допустимы;
• какие текстовые паттерны запрещены;
• куда должен попадать текст каждого класса.

2. Правило one concept -> one canonical place

Нужно явно зафиксировать:

• архитектурная роль PMM живёт в pmm_target_model.md;
• operational rules живут в pmm_transformation_rules.md;
• текстовая дисциплина живёт в comment_policy.md;
• CONTRIBUTING.md не дублирует эти документы, а только ссылается на них.

3. Политика допустимых комментариев

Разрешены только комментарии, которые несут невыводимое из кода знание:

• invariant;
• persistence contract;
• safety note;
• short design note.

Нужно явно запретить:

• исторический шум;
• issue/history narrative в коде;
• tutorial-style prose в ядре;
• пересказ имени функции;
• временные пометки и обещания «удалить потом».

4. Политика допустимых документов

Нужно явно зафиксировать, что канонические docs допускаются только в ограниченных классах:

• target model;
• transformation rules;
• contracts / invariants;
• public API / usage index;
• comment/docs policy.

Остальной текст:

• либо схлопывается;
• либо архивируется;
• либо остаётся в issue / PR discussion, а не в репозитории.

5. Правило сокращения текстовой поверхности

Нужно прямо записать:

• новый markdown-файл — исключение, а не норма;
• любой новый текст обязан либо заменить старый, либо объяснить, почему surface debt допустим;
• дублирующий текст должен удаляться, а не сосуществовать с новым.

6. PR review semantics for text changes

Нужно зафиксировать, что docs/comments PR оценивается прежде всего по:

• отсутствию дублирования;
• уменьшению или как минимум не-росту text surface;
• соответствию canonical-place rule;
• отсутствию process-noise.

Acceptance criteria

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

• не создано ни одного нового markdown-файла;
• docs/comment_policy.md стал каноническим коротким policy doc для docs/comments discipline;
• CONTRIBUTING.md больше не дублирует policy подробно, а только отсылает к canonical docs;
• в diff нет роста docs surface сверх budget;
• зафиксировано правило one concept -> one canonical place;
• зафиксировано правило, что текстовая поверхность PMM должна сокращаться;
• PR не трогает code surface и generated surface.

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

Разрешено:

• ужать существующий policy;
• удалить дублирующий текст;
• заменить подробный пересказ короткой ссылкой на canonical doc.

Запрещено:

• создавать новый policy-файл рядом со старым;
• размазывать одинаковые правила по нескольким markdown-файлам;
• писать длинный tutorial-style explainers;
• добавлять process-docs, временные заметки, roadmap dumps.

Non-goals

• не чистить комментарии по всему коду репозитория в этом issue;
• не переписывать все docs PMM;
• не менять repo-guard policy;
• не менять review workflow;
• не трогать kernel headers и tests.

Риски

1. Агент может начать «улучшать стиль текста» вместо схлопывания дублирования.
2. Policy может оказаться слишком многословной и сама увеличить docs surface.
3. В CONTRIBUTING.md могут остаться дубли policy под видом «удобства для читателя».
4. Может появиться новый markdown-файл “для ясности”, что прямо нарушит цель issue.

PR contract

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

• менять только разрешённый scope;
• не создавать новые markdown-файлы;
• явно показать текстовый surface delta:
  • changed docs
  • removed duplicated lines
  • net markdown delta
• отдельно указать, какие дубли были устранены;
• подтвердить, что code surface = untouched.

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

Успехом считается не просто «обновили comment policy», а то, что после merge:

• текстовых центров смысла стало меньше;
• дублирования стало меньше;
• следующий swarm PR по docs/comments будет труднее распухнуть;
• репозиторий стал меньше по текстовой поверхности, а не больше.