From a49572a29c0c03f873aaea611b3c9fd8f6d131de Mon Sep 17 00:00:00 2001 From: Danil Pismenny Date: Fri, 7 Aug 2026 10:13:37 +0500 Subject: [PATCH 1/2] docs: add MECE governance principle and audit --- docs/mece-template-review.md | 53 ++++++++++++++++++++++++++ template/memory-bank/dna/README.md | 2 +- template/memory-bank/dna/principles.md | 17 +++++---- 3 files changed, 63 insertions(+), 9 deletions(-) create mode 100644 docs/mece-template-review.md diff --git a/docs/mece-template-review.md b/docs/mece-template-review.md new file mode 100644 index 0000000..b6dfeec --- /dev/null +++ b/docs/mece-template-review.md @@ -0,0 +1,53 @@ +# MECE Review: `template/memory-bank` + +Дата ревизии: 2026-08-07 +Ветка: `docs/mece-template-review` + +## Scope и метод + +Проверены DNA, индексы, document boundaries, canonical ownership, routing и +feature artifact catalog. Проверка отвечала на два вопроса: + +1. не создают ли соседние категории или документы конкурирующих владельцев; +2. покрывает ли каждая заявленная классификация свой scope, включая fallback + для пограничных случаев. + +Human-only каталог `template/memory-bank/prompts/` не проверялся семантически; +его содержимое не является workflow dependency. Структурная достижимость +проверена общим lint. + +## Результат + +Критических MECE-нарушений в template не найдено. Большинство потенциальных +пересечений уже разрешены одним из трёх способов: + +- canonical owner и `must_not_define` фиксируют границы ответственности; +- routing order задаёт precedence для взаимоисключающего выбора flow; +- reference views и cross-references явно отделены от новых facts и ownership. + +| Область | Наблюдение | Оценка | +| --- | --- | --- | +| DNA / governance | SSoT, dependency tree и `canonical_for` дают однозначную ownership-модель | Сильная сторона | +| Product ↔ domain ↔ PRD | README-файлы определяют, какие вопросы принадлежат каждому слою и что они не описывают | Сильная сторона | +| Task Routing | Bug/Incident, Epic/Feature и другие близкие predicates могут пересекаться, но порядок маршрутизации и rerouting rules задают precedence | Контролируемое пересечение | +| Feature artifacts | Catalog задаёт trigger, ownership и relation для optional artifacts; reference views не становятся вторыми owners | Сильная сторона | +| UI surfaces | `public-web`, `admin`, `mobile` и `shared-components` разделены по surface; для отсутствующих surfaces предусмотрено удаление ссылки | Сильная сторона | +| Domain documents | glossary/model/rules/states/events/context-map — не взаимоисключающие категории фактов, а ортогональные представления домена | Допустимо; не применять MECE механически | +| 4+1 views | Logical/Process/Development/Physical/Scenarios намеренно пересекаются через traceability | Допустимо; ownership остаётся у canonical owners | +| Top-level index | Каталоги `product`, `domain`, `flows`, `features`, `adr` и другие — разные navigation/lifecycle layers, а не классификация каждого факта | Допустимо; MECE применять только к локальным классификациям | + +## Вывод и действие + +В `dna/principles.md` добавлен принцип **«Структурная полнота и непересечение +(MECE — Mutually Exclusive, Collectively Exhaustive)»**. Он применяется к +декомпозициям, классификациям и индексам только в пределах явно заявленного +scope. Для намеренных пересечений правило требует зафиксировать precedence, +fallback или ограничение scope; открытые списки, ортогональные views и +dependency graphs из-под механического MECE-режима исключены. + +## Проверки + +- `ruby tools/validate-priming-manifests.rb template/memory-bank` — OK; +- `memory-bank-cli lint --scope-root template/memory-bank --entrypoint template/memory-bank/README.md` — OK: 99 файлов, нет broken links, dependency errors или orphan files; +- `memory-bank-cli doctor --profile template` — 0 errors, 0 warnings. + diff --git a/template/memory-bank/dna/README.md b/template/memory-bank/dna/README.md index 2631567..05c4a9c 100644 --- a/template/memory-bank/dna/README.md +++ b/template/memory-bank/dna/README.md @@ -23,7 +23,7 @@ source set `governed_artifact`. [`governance.yaml`](../flows/priming/governance.yaml) и выполни source set `memory_bank_governance`. -- [Principles](principles.md) — фундаментальные принципы проекта: SSoT, атомарность, progressive disclosure. Читать первым. +- [Principles](principles.md) — фундаментальные принципы проекта: SSoT, MECE для применимых классификаций, атомарность и progressive disclosure. Читать первым. - [Document Governance](governance.md) — SSoT implementation, dependency tree. Отвечает на вопрос: кто владеет фактом. - [Frontmatter Schema](frontmatter.md) — schema полей frontmatter. - [Document Lifecycle](lifecycle.md) — maintenance rules, sync checklist. diff --git a/template/memory-bank/dna/principles.md b/template/memory-bank/dna/principles.md index cd57811..93f67f1 100644 --- a/template/memory-bank/dna/principles.md +++ b/template/memory-bank/dna/principles.md @@ -7,11 +7,12 @@ status: active # Principles 1. **SSoT.** Каждый факт имеет ровно одного canonical owner. Дубли = дефект. -2. **Атомарность.** Один файл = одна тема. Разрастается — разбивай. -3. **Компактность.** Документ должен оставаться читаемым. Разрастается — разбивай. -4. **Progressive disclosure.** Сначала обзор, затем ссылки вглубь. Сверху вниз. -5. **WHY / WHAT / HOW.** `prd/`, `use-cases/` и feature `brief.md` = что; `adr/` и feature `design.md` = почему выбран подход; `implementation-plan.md` и код = как выполняем. -6. **Code vs Docs.** Код владеет реализацией. Документация владеет intent, rationale и contracts. -7. **Index-first.** Каждый документ в индексе. Orphan файл = дефект. -8. **Аннотированные ссылки.** Ссылка объясняет: что по ней и зачем читать. -9. Каждое архитектурное решение — отдельный ADR в выделенном разделе. +2. **Структурная полнота и непересечение (MECE — Mutually Exclusive, Collectively Exhaustive).** При декомпозиции, классификации и построении индексов элементы одного уровня должны не пересекаться и вместе покрывать заявленный scope. Если пересечение или неполнота намеренны, явно зафиксируй precedence, fallback или ограничение scope. Не применяй MECE механически к открытым спискам, ортогональным представлениям или графам зависимостей. +3. **Атомарность.** Один файл = одна тема. Разрастается — разбивай. +4. **Компактность.** Документ должен оставаться читаемым. Разрастается — разбивай. +5. **Progressive disclosure.** Сначала обзор, затем ссылки вглубь. Сверху вниз. +6. **WHY / WHAT / HOW.** `prd/`, `use-cases/` и feature `brief.md` = что; `adr/` и feature `design.md` = почему выбран подход; `implementation-plan.md` и код = как выполняем. +7. **Code vs Docs.** Код владеет реализацией. Документация владеет intent, rationale и contracts. +8. **Index-first.** Каждый документ в индексе. Orphan файл = дефект. +9. **Аннотированные ссылки.** Ссылка объясняет: что по ней и зачем читать. +10. Каждое архитектурное решение — отдельный ADR в выделенном разделе. From 14d2178d331b440eedd426458d5b6adecef4cb43 Mon Sep 17 00:00:00 2001 From: Danil Pismenny Date: Fri, 7 Aug 2026 10:16:36 +0500 Subject: [PATCH 2/2] docs: move MECE reference to repository README --- README.md | 1 + docs/mece-template-review.md | 53 ------------------------------------ 2 files changed, 1 insertion(+), 53 deletions(-) delete mode 100644 docs/mece-template-review.md diff --git a/README.md b/README.md index 19347e7..c93f336 100644 --- a/README.md +++ b/README.md @@ -103,6 +103,7 @@ service setup-команды проекта; он намеренно не пер ### Методические источники +- [MECE principle](https://en.wikipedia.org/wiki/MECE_principle) — определение принципа Mutually Exclusive, Collectively Exhaustive: непересекающиеся категории, которые вместе покрывают заявленную область; - Philippe Kruchten, [*Architectural Blueprints — The “4+1” View Model of Software Architecture*](https://arxiv.org/abs/2006.04975) — первичный источник stakeholder-oriented проверки Logical, Process, Development и Physical views через driving scenarios; [краткий обзор](https://en.wikipedia.org/wiki/4%2B1_architectural_view_model); - Nenad Medvidovic, Richard N. Taylor, [*A Classification and Comparison Framework for Software Architecture Description Languages*](https://ics.uci.edu/~taylor/documents/2000-ADLs-TSE.pdf) — источник архитектурной модели components, connectors и configurations. diff --git a/docs/mece-template-review.md b/docs/mece-template-review.md deleted file mode 100644 index b6dfeec..0000000 --- a/docs/mece-template-review.md +++ /dev/null @@ -1,53 +0,0 @@ -# MECE Review: `template/memory-bank` - -Дата ревизии: 2026-08-07 -Ветка: `docs/mece-template-review` - -## Scope и метод - -Проверены DNA, индексы, document boundaries, canonical ownership, routing и -feature artifact catalog. Проверка отвечала на два вопроса: - -1. не создают ли соседние категории или документы конкурирующих владельцев; -2. покрывает ли каждая заявленная классификация свой scope, включая fallback - для пограничных случаев. - -Human-only каталог `template/memory-bank/prompts/` не проверялся семантически; -его содержимое не является workflow dependency. Структурная достижимость -проверена общим lint. - -## Результат - -Критических MECE-нарушений в template не найдено. Большинство потенциальных -пересечений уже разрешены одним из трёх способов: - -- canonical owner и `must_not_define` фиксируют границы ответственности; -- routing order задаёт precedence для взаимоисключающего выбора flow; -- reference views и cross-references явно отделены от новых facts и ownership. - -| Область | Наблюдение | Оценка | -| --- | --- | --- | -| DNA / governance | SSoT, dependency tree и `canonical_for` дают однозначную ownership-модель | Сильная сторона | -| Product ↔ domain ↔ PRD | README-файлы определяют, какие вопросы принадлежат каждому слою и что они не описывают | Сильная сторона | -| Task Routing | Bug/Incident, Epic/Feature и другие близкие predicates могут пересекаться, но порядок маршрутизации и rerouting rules задают precedence | Контролируемое пересечение | -| Feature artifacts | Catalog задаёт trigger, ownership и relation для optional artifacts; reference views не становятся вторыми owners | Сильная сторона | -| UI surfaces | `public-web`, `admin`, `mobile` и `shared-components` разделены по surface; для отсутствующих surfaces предусмотрено удаление ссылки | Сильная сторона | -| Domain documents | glossary/model/rules/states/events/context-map — не взаимоисключающие категории фактов, а ортогональные представления домена | Допустимо; не применять MECE механически | -| 4+1 views | Logical/Process/Development/Physical/Scenarios намеренно пересекаются через traceability | Допустимо; ownership остаётся у canonical owners | -| Top-level index | Каталоги `product`, `domain`, `flows`, `features`, `adr` и другие — разные navigation/lifecycle layers, а не классификация каждого факта | Допустимо; MECE применять только к локальным классификациям | - -## Вывод и действие - -В `dna/principles.md` добавлен принцип **«Структурная полнота и непересечение -(MECE — Mutually Exclusive, Collectively Exhaustive)»**. Он применяется к -декомпозициям, классификациям и индексам только в пределах явно заявленного -scope. Для намеренных пересечений правило требует зафиксировать precedence, -fallback или ограничение scope; открытые списки, ортогональные views и -dependency graphs из-под механического MECE-режима исключены. - -## Проверки - -- `ruby tools/validate-priming-manifests.rb template/memory-bank` — OK; -- `memory-bank-cli lint --scope-root template/memory-bank --entrypoint template/memory-bank/README.md` — OK: 99 файлов, нет broken links, dependency errors или orphan files; -- `memory-bank-cli doctor --profile template` — 0 errors, 0 warnings. -