# [governance/kernel-compaction] Запретить `.inc`-шардинг в `include/pmm/**` как способ обхода лимита размера файла

[netkeep80]

Контекст

В PMM уже появился нежелательный паттерн:

• части крупных header-файлов выносятся в .inc-файлы;
• затем основной .h подключает их обратно через #include;
• фактическая сложность и связность не уменьшаются;
• уменьшается только видимая длина одного файла.

Это плохое направление для controlled compaction.

Особенно проблемно то, что такой вынос начинает использоваться как способ
обойти operational limit вроде “header не должен превышать 1500 строк”.

Для PMM это неверная стратегия.

Если header становится слишком большим, это должно вести к:

• реальному сокращению кода,
• устранению дублирования,
• выделению самостоятельного модуля в нормальный .h,
• уменьшению ответственности конкретного файла,

а не к textual sharding через .inc.

Цель

Зафиксировать в PMM жёсткое правило:

новые .inc / .inl / .ipp файлы внутри include/pmm/** запрещены как способ декомпозиции или обхода лимита размера файла.

Лимит размера должен толкать к реальному refactor/compaction,
а не к псевдо-декомпозиции.

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

governance/kernel-compaction

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

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

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

• запретить ложное “уменьшение” репозитория через разрезание одного header-а на include-шарды;
• направить swarm-агентов в сторону реального structural compaction;
• сделать file-size limit архитектурно полезным, а не легко обходящимся;
• уменьшить риск дальнейшего расползания PMM при сохранении тех же зависимостей и той же сложности.

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

• docs/pmm_transformation_rules.md
• docs/comment_policy.md — только если нужна краткая sync-формулировка
• CONTRIBUTING.md — только если нужна минимальная operational note
• repo-policy.json
• при необходимости: scripts/check-docs-consistency.sh — только если нужен минимальный sync с policy wording
• docs/index.md — только если нужна минимальная ссылка на уточнённый canonical rule

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

• include/** code changes
• single_include/**
• tests/**
• examples/**
• demo/**
• .github/**
• создание новых markdown-файлов
• любые behavior/API changes

Surface budget

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

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

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

1. Явный запрет include-sharding

В canonical governance PMM должно быть явно записано:

Запрещено уменьшать header/file surface путём выноса частей того же модуля
в .inc, .inl, .ipp и аналогичные include-шарды внутри include/pmm/**.

2. Явное разрешение только на real module extraction

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

• compaction — уменьшение/упрощение существующего кода;
• real module extraction — вынос в самостоятельный нормальный .h-модуль
  с собственной ролью, а не “вторая половина того же файла”.

3. Новая трактовка лимита размера

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

Если header приближается к operational limit (например 1500 строк),
это считается сигналом к:

• уменьшению ответственности,
• removal of duplication,
• real refactor,

а не оправданием .inc-шардинга.

4. Policy-level enforcement

repo-policy.json должен быть обновлён так, чтобы новые файлы и include-паттерны
вроде:

• include/pmm/**/*.inc
• include/pmm/**/*.inl
• include/pmm/**/*.ipp

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

Если этого можно добиться path/content policy — сделать так.
Не вводить новый repo-guard feature в этом issue.

5. Review semantics

Reviewer должен оценивать такие попытки так:

• “file got shorter because of .inc split” — это не compaction;
• “same module fragmented into include-shards” — это policy violation;
• “new normal header with a real module boundary” — может быть допустим,
  если реально уменьшает связность и ответственность.

Acceptance criteria

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

• canonical governance text PMM явно запрещает .inc-шардинг как способ обхода file-size limit;
• repo-policy.json делает появление новых .inc / .inl / .ipp в include/pmm/** policy violation;
• rule distinguishes forbidden include-sharding from allowed real module extraction;
• issue не меняет kernel/code surface;
• generated surface не затронут.

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

Разрешено:

• уточнить существующие governance rules;
• сделать path/content-level policy tighter;
• коротко зафиксировать reviewer semantics.

Запрещено:

• заводить новый длинный design doc;
• менять существующие .inc файлы в этом issue;
• пытаться сразу чинить старый debt и policy одновременно.

Non-goals

• не удалять существующие .inc-файлы в этом issue;
• не переписывать persist_memory_manager.h прямо сейчас;
• не менять single-header generation pipeline;
• не вводить новый repo-guard capability, если хватает текущих policy primitives.

Риски

1. Формулировка может оказаться слишком широкой и случайно запретить legitimate module extraction.
2. Формулировка может оказаться слишком мягкой и оставить лазейки через новые suffix-паттерны.
3. Агент может снова попытаться решить проблему file-size limit через naming trick вместо настоящего refactor.

PR contract

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

• менять только governance/policy wording;
• не трогать kernel code;
• не трогать generated surface;
• явно показать:
  • какие path/content policy rules добавлены;
  • как теперь различаются forbidden include-sharding и allowed real module extraction.

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

Успехом считается не просто “написали, что .inc плохо”, а то, что после merge:

• swarm-агент больше не сможет легитимно дробить PMM headers на include-шарды;
• file-size limit станет толкать к настоящему compaction/refactor;
• репозиторий будет схлопываться структурно, а не только визуально.