From 7774c39cc673cecf55af0da72039e5571f471eb1 Mon Sep 17 00:00:00 2001 From: Danil Pismenny Date: Sun, 6 Sep 2026 23:52:09 +0300 Subject: [PATCH 1/2] docs: focus DNA on documentation trust --- README.md | 19 ++- README.ru.md | 20 ++- docs/context-priming.md | 6 + docs/glossary.md | 37 +++-- memory-bank/README.md | 2 +- .../ADR-002-documentation-trust-boundary.md | 102 ++++++++++++ memory-bank/adr/README.md | 3 + memory-bank/features/FT-DNA/README.md | 20 +++ memory-bank/features/FT-DNA/brief.md | 106 ++++++++++++ memory-bank/features/FT-DNA/design.md | 110 +++++++++++++ .../features/FT-DNA/implementation-plan.md | 154 ++++++++++++++++++ memory-bank/features/README.md | 2 + template/memory-bank/README.md | 2 +- template/memory-bank/dna/README.md | 44 +++-- template/memory-bank/dna/cross-references.md | 38 ++++- template/memory-bank/dna/frontmatter.md | 64 ++++++-- template/memory-bank/dna/governance.md | 91 +++++++++-- template/memory-bank/dna/lifecycle.md | 66 ++++++-- template/memory-bank/dna/principles.md | 42 +++-- template/memory-bank/flows/README.md | 5 + .../memory-bank/flows/autonomy-boundaries.md | 19 +++ .../flows/priming/context-priming.md | 5 + 22 files changed, 853 insertions(+), 104 deletions(-) create mode 100644 memory-bank/adr/ADR-002-documentation-trust-boundary.md create mode 100644 memory-bank/features/FT-DNA/README.md create mode 100644 memory-bank/features/FT-DNA/brief.md create mode 100644 memory-bank/features/FT-DNA/design.md create mode 100644 memory-bank/features/FT-DNA/implementation-plan.md diff --git a/README.md b/README.md index dadbbd6..ecffbff 100644 --- a/README.md +++ b/README.md @@ -136,13 +136,18 @@ or another agent cannot resume the work from repository state. ### DNA and Single Source of Truth -The `dna/` layer is the constitution of the knowledge base. It defines Single -Source of Truth, document ownership, dependency direction, lifecycle, -frontmatter, and navigation rules. - -A canonical document owns a fact. Another document may derive a requirement, -plan, or view from it, but must preserve the dependency. When documents -disagree, ownership and dependency direction identify the authoritative source. +The `dna/` layer defines rules for trustworthy project documentation: source +ownership, evidence, scope, freshness, publication metadata, and navigation. +The `flows/` layer owns task execution, agent permissions, and delivery checks. + +A canonical document owns a claim within a declared context. Derived +requirements, plans, and views preserve the source and its limitations. +An `active` publication may contain an explicitly unverified assumption; +publication status alone does not prove a claim. + +When documents disagree, compare their claims, scopes, owners, and semantic +dependencies. Ambiguous ownership remains an explicit conflict until resolved; +a newer edit does not automatically win. ### Project knowledge diff --git a/README.ru.md b/README.ru.md index fee3c44..37839cc 100644 --- a/README.ru.md +++ b/README.ru.md @@ -139,13 +139,19 @@ Memory Bank полезен, когда замысел проекта прихо ### ДНК и единственный источник истины -`dna/` — конституция базы знаний. Здесь определены принцип единственного источника истины, -владение документами, направление зависимостей, жизненный цикл, метаданные и правила -навигации. - -Канонический документ владеет фактом. Другой документ может вывести из него требование, план или -представление, но обязан сохранить зависимость от источника. Если документы противоречат друг -другу, правила владения и направление зависимостей указывают авторитетный источник. +`dna/` задаёт правила достоверной документации проекта: владение источниками, +основания утверждений, область применимости, актуальность, метаданные публикации +и навигацию. В `flows/` находятся исполнение задач, полномочия агента и проверки +разработки. + +Канонический документ владеет утверждением в объявленном контексте. Производные +требования, планы и представления сохраняют источник и его ограничения. +Публикация со статусом `active` может содержать явно непроверенное предположение; +сам статус не доказывает утверждение. + +При расхождении документов сравнивают утверждения, области применимости, +владельцев и смысловые зависимости. Неоднозначное владение остаётся явным +конфликтом до разрешения; более свежая правка не получает автоматический приоритет. ### Знания о проекте diff --git a/docs/context-priming.md b/docs/context-priming.md index 2b41a15..3ea4650 100644 --- a/docs/context-priming.md +++ b/docs/context-priming.md @@ -55,6 +55,12 @@ governed-артефакт, выполняет shared `cross-references.md`. Incident containment не ждёт этот baseline, но он обязателен до создания или изменения governed incident-артефакта. +При изменении governance-ядра дополнительно выполняется source set +`memory_bank_governance` из +[governance.yaml](../template/memory-bank/flows/priming/governance.yaml). +Порядок задаёт [Context Priming Contract](../template/memory-bank/flows/priming/context-priming.md); +DNA описывает качество документов, а обязательное чтение относится к process-layer. + Canonical process-file указывает один YAML manifest и source sets для своих стадий. Сам manifest содержит только exact paths и bounded masks. Перед чтением masks разворачиваются против одной immutable revision в **exact input diff --git a/docs/glossary.md b/docs/glossary.md index 794c07f..2070e97 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -22,15 +22,17 @@ canonical owner факта и как downstream-документы наслед ## SSoT -`SSoT` (`Single Source of Truth`) — принцип, по которому каждый факт имеет -ровно одного canonical owner. Если один и тот же факт начинает жить в -нескольких местах, это считается дефектом документации. +`SSoT` (`Single Source of Truth`) — принцип, по которому у каждого утверждения +в заданном контексте ровно один canonical owner. Производный обзор сохраняет +ссылку на owner, смысл и ограничения источника; независимые копии одного +утверждения считаются дефектом документации. ## Canonical Owner -`Canonical owner` — документ, который владеет конкретным фактом и имеет -приоритет над downstream-описаниями. Изменение такого документа должно -считаться изменением источника истины, а не просто заметки. +`Canonical owner` — документ, в котором определено конкретное утверждение +для указанного контекста. Downstream сохраняет его смысл и ограничения в +импортированном scope. Owner формулировки и источник evidence могут различаться: +владение утверждением само по себе не доказывает его. ## Governed Document @@ -41,16 +43,18 @@ governance-правилам и имеет валидный YAML frontmatter. В ## Authoritative Document -`Authoritative document` — governed-документ, который сейчас считается -действующим источником истины. В модели этого шаблона authoritative считается -только документ со `status: active`. +`Authoritative document` — governed-документ в действующем наборе источников. +`status: active` — необходимое условие; конкретный claim используется с учётом +его типа, scope, основания и lifecycle сущности. Active-документ может содержать +явно непроверенное предположение. [DNA governance](../template/memory-bank/dna/governance.md) +определяет применимость и правила конфликтов. ## Dependency Tree -`Dependency tree` — ориентированная структура зависимостей между документами, -построенная через `derived_from`. Authority течёт по ней upstream → downstream, -поэтому изменение корневого или промежуточного документа может потребовать -обновления производных материалов. Циклы запрещены. +`Dependency tree` — историческое название направленного ациклического графа +semantic dependencies через `derived_from`. Прямых upstream может быть несколько; +их authority относится только к импортированным утверждениям и ограничениям. +Обычная навигация и ссылки на evidence не создают рёбра этого графа. ## Upstream and Downstream @@ -69,8 +73,8 @@ upstream-документы. Элементом может быть путь л ## Canonical For `canonical_for` — frontmatter-поле, которым документ явно объявляет факты или -артефакты, которыми он владеет. Оно помогает выбрать owner, но не заменяет -SSoT, status и порядок зависимостей. +артефакты, которыми он владеет. Оно называет ownership в объявленном scope, но не доказывает claim и не +отменяет upstream constraints. Формат определяет [schema DNA](../template/memory-bank/dna/frontmatter.md). ## Progressive Disclosure @@ -113,7 +117,8 @@ downstream destination — `memory-bank/`. `Process layer` — часть knowledge layer, которая описывает lifecycle, workflows, gates и шаблоны исполнения. В source template она в основном сосредоточена в `template/memory-bank/flows/`, а после установки — в -`memory-bank/flows/`. +`memory-bank/flows/`. DNA задаёт критерии достоверности документации, а +process layer — routing, действия, полномочия и проверки при работе с ней. ## Task Routing diff --git a/memory-bank/README.md b/memory-bank/README.md index 0c95ea8..e2f21be 100644 --- a/memory-bank/README.md +++ b/memory-bank/README.md @@ -57,7 +57,7 @@ payload. Реальные файлы здесь — только то, что п Читать, когда нужно: задать architecture patterns, frontend rules, testing conventions, coding style и git workflow целевой системы. - [`dna/README.md`](dna/README.md) - Читать, когда нужно: проверить SSoT rules, frontmatter contract и governance-правила документации. + Читать, когда нужно: проверить достоверность, основания и актуальность утверждений, ownership и metadata документации. - [`flows/README.md`](flows/README.md) Читать, когда нужно: создать use case, epic/feature package, применить BDD-практику, провести артефакт по lifecycle gates, узнать границы автономии агента, выбрать validation profile или использовать шаблон. diff --git a/memory-bank/adr/ADR-002-documentation-trust-boundary.md b/memory-bank/adr/ADR-002-documentation-trust-boundary.md new file mode 100644 index 0000000..d4b1c1b --- /dev/null +++ b/memory-bank/adr/ADR-002-documentation-trust-boundary.md @@ -0,0 +1,102 @@ +--- +title: "ADR-002: Выделить достоверность документации как назначение DNA" +doc_kind: adr +doc_function: canonical +purpose: Основания и последствия разделения документационного ядра и процессных правил. +derived_from: + - ../features/FT-DNA/brief.md +status: active +decision_status: accepted +date: 2026-09-06 +decision_makers: + - Danil Pismenny (назначение и граница) +authors: + - Codex +consulted: [] +informed: [] +audience: humans_and_agents +--- + +# ADR-002: Выделить достоверность документации как назначение DNA + +## Контекст + +В исходной revision `f1f04de843aef45a2425d4a7351d577bbf89e940` DNA содержит +шесть файлов. Его правила определяют SSoT, metadata и обслуживание, но +`active` недостаточно отделён от подтверждённости, а чтение baseline и реакция +агента на конфликт смешаны с критериями качества документов. + +Данил подтвердил назначение DNA в текущей задаче: поддерживать достоверную +документацию; управление работой агента важно как отдельный слой. Основание +scope и acceptance — [FT-DNA brief](../features/FT-DNA/brief.md). + +## Границы решения + +Общий payload DNA и затронутые process owners. Runtime, внешний CLI, +downstream migrations и публикация исключены. [ADR-001](ADR-001-introduce-design-pack.md) +прочитан: design-pack ownership сохраняется, это решение его не заменяет. + +## Драйверы решения + +1. Читатель различает ожидаемое, наблюдаемое и неподтверждённое. +2. Owner, источник и область применимости определимы без догадки. +3. Правила документации применимы и без agent runner. +4. Существующие пути, fields и enum остаются совместимыми. +5. Дополнительная формальность оправдывается предотвращаемой ошибкой. + +## Рассмотренные варианты + +| Вариант | Плюсы | Минусы | Оценка | +| --- | --- | --- | --- | +| Сохранить модель, уточнить формулировки по месту | Минимальный diff и привычные правила | Неявная граница с агентскими инструкциями остаётся | Допустим как малый шаг, но не закрывает выбранное назначение | +| Уточнить DNA и использовать существующий flows для исполнения | Раздельные owners без нового каталога; сохраняются пути и формат | Нужны согласованные правки нескольких документов | Выбран по минимальной стоимости сопровождения | +| Выделить новый независимый пакет документационного ядра | Возможны отдельные версии и установка без flows | Потребуются CLI/release изменения и migration contract | Отложен: потребность в отдельной поставке не подтверждена | + +## Решение + +DNA задаёт критерии достоверности, ownership, semantic dependencies, +публикационные состояния и навигацию документации. Источник нормы, evidence +наблюдения и статус публикации различаются. Процесс исполнения, полномочия, +обязательное чтение и delivery gates остаются у существующих owners в `flows/`. +Разделение семантическое: самостоятельный installable package не создаётся. + +Решение проверено автором по E.C.A.D.R.: проблема, альтернативы, scope, +consequences и Confirmation заданы. Согласование назначения — текущая задача +Данила; дополнительные approvals для локального документационного изменения +не требуются. Независимая проверка реализации выполняется отдельно. + +## Последствия + +- Положительные: active-гипотеза не выглядит доказанным фактом; требование и + наблюдение не подменяют друг друга; конфликт не разрешается датой файла. +- Отрицательные: авторам потребуется указывать основание и scope существенных + утверждений; semantic review останется нужен при зелёном lint. +- Организационные: DNA владеет качеством знания, flows — работой с ним; + rationale остаётся здесь, living rules — в payload. + +## Риски и mitigation + +Новая модель может превратиться в обязательную разметку каждого предложения. +Поэтому тип утверждения определяется понятным текстом и контекстом секции; +новые mandatory YAML fields, evidence registry и числовые trust scores не вводятся. +Источники и revision нужны там, где они влияют на проверяемость и актуальность. + +## Confirmation + +Owner: исполнитель FT-DNA, проверяющий — независимый code-converge. +План: проверить SC/NEG из brief, выполнить priming validator, lint, doctor, +projection check и diff check; затем получить structured document-review verdict. +Evidence: локальный внешний carrier из brief. Зелёная структурная проверка +сама по себе не подтверждает истинность утверждений. + +## Условия пересмотра + +- Потребовалась отдельная установка/версионирование DNA без flows. +- Реальные задачи показывают неоднозначность типов утверждений или authority. +- CLI требует incompatible schema либо новая metadata оправдана проверкой. + +## Follow-up + +- [DNA](../dna/README.md) — living trust, ownership и freshness rules. +- [Flows](../flows/README.md) — исполнение, priming и полномочия. +- [FT-DNA](../features/FT-DNA/README.md) — текущая реализация и verification. diff --git a/memory-bank/adr/README.md b/memory-bank/adr/README.md index 499f8bb..ce2ad26 100644 --- a/memory-bank/adr/README.md +++ b/memory-bank/adr/README.md @@ -25,6 +25,9 @@ audience: humans_and_agents ## Аннотированный индекс +- [ADR-002: Достоверность документации](ADR-002-documentation-trust-boundary.md) + Accepted: назначение DNA и семантическая граница с процессным слоем. + - [`ADR-001-introduce-design-pack.md`](ADR-001-introduce-design-pack.md) Accepted: разделить semantic design layer, documentary design pack и root `design.md`, а также закрепить aggregate и direct ownership solution facts. diff --git a/memory-bank/features/FT-DNA/README.md b/memory-bank/features/FT-DNA/README.md new file mode 100644 index 0000000..b6eeb0a --- /dev/null +++ b/memory-bank/features/FT-DNA/README.md @@ -0,0 +1,20 @@ +--- +title: "FT-DNA: Достоверность документации" +doc_kind: feature +doc_function: index +purpose: Навигация по пересмотру назначения DNA и его границы с процессным слоем. +derived_from: + - ../../dna/governance.md + - brief.md +status: active +audience: humans_and_agents +--- + +# FT-DNA: Достоверность документации + +## Аннотированный индекс + +- [Brief](brief.md) — принятые границы задачи, требования и проверка результата. +- [Design](design.md) — выбранные owners, совместимость и анализ сценариев. +- [Implementation plan](implementation-plan.md) — последовательность, grounding и проверки. +- [ADR-002](../../adr/ADR-002-documentation-trust-boundary.md) — основания разделения DNA / flows. diff --git a/memory-bank/features/FT-DNA/brief.md b/memory-bank/features/FT-DNA/brief.md new file mode 100644 index 0000000..477700b --- /dev/null +++ b/memory-bank/features/FT-DNA/brief.md @@ -0,0 +1,106 @@ +--- +title: "FT-DNA: Достоверность документации" +doc_kind: feature +doc_function: canonical +purpose: Требования к пересмотру DNA как основы достоверной документации. +derived_from: + - ../../flows/feature.md + - ../../flows/feature-requirements.md +status: active +delivery_status: in_progress +audience: humans_and_agents +--- + +# FT-DNA: Достоверность документации + +## What + +### Problem and outcome + +DNA объединяет принципы документации, формат и инструкции агенту, но слабо +различает авторитетность источника и подтверждённость утверждения. Данил в +текущей задаче подтвердил назначение DNA: поддерживать достоверную документацию; +управление работой агента относится к отдельному слою. Результат — читатель +может определить owner, основание и применимость утверждения и найти правила +исполнения у отдельного process owner. + +Route: Feature Flow — меняется общий документационный контракт, подход требует +design; Small Change не подходит. Одна delivery-unit, без runtime изменений. +Authority source: текущая задача Данила от 2026-09-06; подготовка локальных +изменений разрешена. Публикация и merge в scope не входят. + +### Requirements + +Для всех требований: источник — задача выше, priority — must, accountable owner +— maintainer Memory Bank; метод — semantic inspection и проверки ниже. + +| ID | Class | Требуемый результат | Acceptance | +| --- | --- | --- | --- | +| REQ-01 | stakeholder / product | DNA явно отвечает за достоверность документации, правила исполнения имеют отдельного владельца | SC-01 | +| REQ-02 | functional | Читатель различает требование, наблюдение и предположение; может установить owner и область применимости | SC-02, NEG-01, NEG-02 | +| REQ-03 | quality attribute | Изменение источника, конфликт и устаревание имеют однозначные последствия для зависимых утверждений | SC-03, NEG-03 | +| REQ-04 | compatibility | Существующие пути, enum и YAML-формы сохраняются; ссылки и manifests разрешимы | SC-04 | + +### Applicability + +| Class | Decision / rationale | +| --- | --- | +| stakeholder / product | applicable: REQ-01 | +| functional | applicable: REQ-02 | +| quality attribute | applicable: REQ-03 | +| compatibility | applicable: REQ-04 | +| constraint | applicable: CON-01 | +| verification / acceptance | applicable: SC/NEG/CHK/EVID ниже | +| performance, interface, data, security, safety, regulatory / compliance, operational, deployment / rollout | not-applicable: меняется документационная семантика; runtime, сериализация, окружения и внешние обязательства не меняются | + +### Non-scope and constraints + +- NS-01: новый agent runner, новый delivery lifecycle, переписывание всех flows. +- NS-02: изменения внешнего CLI, массовая миграция downstream-проектов, публикация. +- CON-01: payload generic; история этой задачи живёт только в project-local package. +- Blocking decisions: none; назначение DNA подтверждено пользователем. + +## Design Requirement Decision + +Design required: yes — нужны выбор границы ответственности и compatibility analysis. + +## Validation Profile Decision + +Validation profile: documentation. Меняются Markdown-правила и навигация; +executable behavior, wire/schema format, config и release path не меняются. +Существующие fields/enums сохраняются. Downgrade approval: none. + +## Verify + +EC-01: все SC/NEG имеют ожидаемые результаты; структурные проверки проходят, +независимая document review возвращает структурированный clean verdict без +findings. Любые findings или operational error оставляют проверку непройденной. + +| ID | Context → event → observable outcome | Requirement / check | +| --- | --- | --- | +| SC-01 | Читатель ищет критерии доверия и полномочия на правку → читает DNA → находит критерии в DNA, полномочия у process owner | REQ-01 / CHK-01 | +| SC-02 | Есть нормативный лимит 30 секунд и измерение 45 секунд → сопоставление → требование и наблюдение сохраняются раздельно, расхождение явно названо | REQ-02 / CHK-01 | +| SC-03 | Изменён canonical source → проверка производного описания → оно обновлено либо его неподтверждённая часть явно ограничена | REQ-03 / CHK-01 | +| SC-04 | Существующий документ использует status и обе формы derived_from → проверка обновлённого template → формат и пути остаются допустимыми | REQ-04 / CHK-02 | +| NEG-01 | Два active owner претендуют на один scope → сравнение → дата файла или порядок списка не выбирают победителя | REQ-02 / CHK-01 | +| NEG-02 | active-документ содержит неподтверждённое предположение → использование → active не превращает его в установленный факт | REQ-02 / CHK-01 | +| NEG-03 | Новая инструкция агенту → размещение → DNA не становится владельцем execution procedure | REQ-01, REQ-03 / CHK-01 | + +| Check | Метод и ожидаемый результат | Evidence | +| --- | --- | --- | +| CHK-01 | Semantic read-through SC/NEG и независимая code-converge document review; все outcomes различимы, получен structured clean verdict без findings | EVID-01: structured verdict и scenario results в revision-bound Git note | +| CHK-02 | Priming validator, template lint, template doctor, projection check, diff whitespace check; нет новых ошибок | EVID-02: command logs в той же revision-bound Git note | + +Evidence сохраняется в локальном Git carrier вне проверяемого дерева: +`refs/notes/dna-trust-review`, note привязана к полному commit SHA проверяемого +снимка. Каждый снимок удерживается отдельной именованной Git-ссылкой, например +`refs/review-candidates/ft-dna/plan-4`. Имя состоит из префикса +`refs/review-candidates/ft-dna/`, фазы (`plan` или `execution`), дефиса и номера +итерации; префикс сам по себе не является ref. При новой revision создаётся +новое имя. Снимки сохраняются независимо от cache и доступны будущим локальным читателям. +Проверяемые файлы и snapshot tree должны совпадать; note содержит SHA, reviewer, +structured verdict, outcomes SC/NEG и command outputs с exit codes. +Чтение: `git notes --ref=dna-trust-review show `. +При разрешённой передаче работы экспортируются и candidate refs, и notes ref; +одна branch без notes не считается полной передачей evidence. +`~/.cache/memory-bank-dna-trust/` хранит только вспомогательные diagnostics. diff --git a/memory-bank/features/FT-DNA/design.md b/memory-bank/features/FT-DNA/design.md new file mode 100644 index 0000000..5c4bb0f --- /dev/null +++ b/memory-bank/features/FT-DNA/design.md @@ -0,0 +1,110 @@ +--- +title: "FT-DNA: Design" +doc_kind: feature +doc_function: canonical +purpose: Размещение правил достоверности и перенос process obligations к существующим owners. +derived_from: + - brief.md + - ../../adr/ADR-002-documentation-trust-boundary.md +status: active +audience: humans_and_agents +--- + +# FT-DNA: Design + +## Design Pack + +| Artifact | Relation | Direct ownership | Readiness | +| --- | --- | --- | --- | +| [design.md](design.md) | root | SOL, INV, FM и compatibility ниже | active | +| [ADR-002](../../adr/ADR-002-documentation-trust-boundary.md) | external-dependency | Выбор границы и rationale | active / accepted | + +## Selected Solution + +- SOL-01 (REQ-01): сохранить каталог из шести файлов; DNA README объясняет + назначение и границу. Инструкции чтения принадлежат context-priming, действия + при конфликте — autonomy-boundaries. WHY/WHAT/HOW и выбор ADR уже имеют + process owners; principles перестаёт задавать конкретные delivery artifacts. +- SOL-02 (REQ-02): principles и governance различают норму, наблюдение, вывод + и предположение. Существенный claim имеет scope, основание и owner; + это prose contract без обязательной разметки каждого предложения. + Существенно утверждение, от которого зависят требования, решения, действия + или выводы читателя. Вид, scope и основание допустимо указать в самой + формулировке, общей декларации секции либо по явной аннотированной ссылке; + общий контекст применяется к секции целиком, локальное исключение называется + рядом с утверждением. Owner определяется по canonical_for или явно описанной + границе документа. Reviewer берёт каждое существенное изменённое утверждение + и должен найти эти сведения без догадки; для наблюдения также нужны условия + и дата/revision, когда они влияют на применимость. Отсутствующее основание + обозначается как unknown или непроверенное предположение. Нельзя объявить + проверку пройденной только по status: active или наличию ссылки. +- SOL-03 (REQ-03): governance описывает неоднозначный ownership и import scope; + lifecycle — публикацию, утрату актуальности и последствия source changes; + cross-references — различие навигации, semantic dependency и evidence. +- SOL-04 (REQ-04): сохранить enum, обе формы derived_from и прежние пути. + canonical_for и doc_kind/doc_function описать в schema; старый heading в + governance оставить как переход. Glossary и затронутые индексы синхронизировать. + +## Constraints and Failure Modes + +- INV-01: generic payload не зависит от project-local ADR/FT-DNA; эти artifacts + фиксируют историю изменения, а не становятся upstream шаблона. +- INV-02: обычная ссылка не даёт semantic authority; canonical_for не делает + утверждение доказанным и не разрешает нарушать imported constraints. +- FM-01: смешение нормы и наблюдения → разделение claims и явное расхождение. +- FM-02: duplicate owner, неизвестный scope или устаревшее evidence → affected + claim помечается как unresolved; текст не выбирает победителя эвристически. +- FM-03: чрезмерная формальность → без новых mandatory fields, файлов и + массового backfill; проверяются существенные изменяемые утверждения. + +## Architecture Coverage + +C4-00: not required — Markdown template, code/runtime boundaries не меняются. + +| Aspect | Status / result | +| --- | --- | +| Components / responsibilities | covered: SOL-01–04, документальные owners | +| Connectors / interactions | covered: semantic links и навигация, SOL-03–04 | +| Configuration / topology | N/A: нет runtime/config изменений | +| Behavioral semantics | covered: документальная интерпретация, FM-01–02 | +| Quality / evolution | covered: compatibility, INV-01–02, FM-03 | + +## 4+1 Viewpoint Coverage Decision + +| View | Status | Stakeholder / concern / refs | +| --- | --- | --- | +| Logical | covered | Читатель: достоверность, SOL-01–04 | +| Scenarios | covered | Автор и reviewer: все SC/NEG из brief, таблица ниже | +| Process | N/A | Runtime interactions не меняются | +| Development | N/A | Code/module responsibilities не меняются | +| Physical | N/A | Runtime placement не меняется | + +## Cross-View Correspondence / Traceability + +Для всех строк Process/Development/Physical: N/A по решениям выше. + +| Scenario | Requirement | Solution / failure | Check / evidence | +| --- | --- | --- | --- | +| SC-01, NEG-03 | REQ-01 | SOL-01, INV-01 | CHK-01 / EVID-01 | +| SC-02, NEG-02 | REQ-02 | SOL-02, FM-01 | CHK-01 / EVID-01 | +| NEG-01 | REQ-02 | SOL-03, INV-02, FM-02 | CHK-01 / EVID-01 | +| SC-03 | REQ-03 | SOL-03, FM-02 | CHK-01 / EVID-01 | +| SC-04 | REQ-04 | SOL-04, FM-03 | CHK-02 / EVID-02 | + +## Design Verification + +| Analysis | Required | Method / result | +| --- | --- | --- | +| Contract compatibility | yes | Сверены DNA, glossary, ADR index, priming manifests: пути и metadata сохраняются; уточнение prose не требует CLI migration | +| State / transition completeness | yes | active/draft/archived и отдельные entity states остаются; active+proposed ADR не означает accepted | +| Failure propagation | yes | Source change и duplicate owners разобраны в SC-03/NEG-01: затронутые claims ограничиваются, независимые сохраняются | +| Concurrency / ordering | no | Нет executable concurrency change | +| Security boundaries | no | Нет изменения доступа или исполнения внешних действий | +| Capacity / latency | no | Нет runtime path | +| Migration / evolution safety | yes | Совместимость проверена по существующим fields, обеим формам derived_from и ссылкам; lint/doctor подтвердят реализацию | + +## Alternatives and Execution Boundary + +Альтернативы и trade-offs принадлежат ADR-002; отдельные local decisions не нужны. +Rollback: локальный revert целого документационного изменения, без data migration. +Delivery и rollout вне этой локальной задачи; runtime contracts не создаются. diff --git a/memory-bank/features/FT-DNA/implementation-plan.md b/memory-bank/features/FT-DNA/implementation-plan.md new file mode 100644 index 0000000..895a4d5 --- /dev/null +++ b/memory-bank/features/FT-DNA/implementation-plan.md @@ -0,0 +1,154 @@ +--- +title: "FT-DNA: Implementation Plan" +doc_kind: feature +doc_function: derived +purpose: Локальное исполнение пересмотра DNA и проверка совместимости документов. +derived_from: + - brief.md + - design.md +status: active +audience: humans_and_agents +--- + +# FT-DNA: Implementation Plan + +## Grounding Evidence + +Grounded repository revision: `f1f04de843aef45a2425d4a7351d577bbf89e940`. +Grounded at: 2026-09-06. Environment: локальный macOS checkout, Ruby и +установленные memory-bank-cli / code-converge. Runtime приложения отсутствует. + +| ID | Inspected path / command | Observed fact | Plan impact | +| --- | --- | --- | --- | +| GRND-01 | Шесть файлов `template/memory-bank/dna/`, перечисленных ниже | 208 строк; active authority, dependency tree, agent conflict instruction и priming в README | Уточнить существующих owners, сохранить пути | +| GRND-02 | `template/memory-bank/flows/autonomy-boundaries.md`, `template/memory-bank/flows/priming/context-priming.md` | Уже владеют полномочиями и чтением baseline | Перенести обязанности без нового process layer | +| GRND-03 | `AGENTS.md`, `.github/workflows/ci.yml`, `tools/validate-priming-manifests.rb`, `tools/refresh-memory-bank-projection.rb` | Существуют link/doctor/priming checks, downstream smoke; generic instance — symlinks | Использовать existing checks; новых prose-mirroring tests не нужно | +| GRND-04 | `memory-bank-cli lint --scope-root template/memory-bank --entrypoint template/memory-bank/README.md`; `memory-bank-cli doctor --profile template` | До изменения payload оба проходят; doctor: 0 errors, 0 warnings | Новая ошибка считается regression | + +## Implementation Priming / Exact Realization + +Все пути repo-relative. Sections называют исходные заголовки; review проверяет +также новую семантику этих owners. Для строк 1–6 основание GRND-01, для 7–8 +GRND-02, для 9–13 — supporting sync, проверенный при discovery. + +| Order | Exact path | Section / purpose | Implements | Step | +| --- | --- | --- | --- | --- | +| 1 | `template/memory-bank/dna/principles.md` | Principles: назначение и основания знания | REQ-01–02 / SOL-01–02 | STEP-01 | +| 2 | `template/memory-bank/dna/governance.md` | SSoT Implementation / Source Dependency Tree: ownership, scope, evidence | REQ-02–03 / SOL-02–03, INV-02, FM-01–02 | STEP-01 | +| 3 | `template/memory-bank/dna/frontmatter.md` | Обязательные / Условно обязательные: совместимая schema | REQ-04 / SOL-04, FM-03 | STEP-01 | +| 4 | `template/memory-bank/dna/lifecycle.md` | Maintenance Rules / Sync Checklist: актуальность | REQ-03 / SOL-03, FM-02 | STEP-01 | +| 5 | `template/memory-bank/dna/cross-references.md` | Code → docs / Docs → code: виды ссылок и evidence | REQ-02–03 / SOL-03 | STEP-01 | +| 6 | `template/memory-bank/dna/README.md` | DNA Index / Universal Governance Baseline: граница и маршруты | REQ-01 / SOL-01 | STEP-02 | +| 7 | `template/memory-bank/flows/autonomy-boundaries.md` | Автопилот / Structured Decision Protocol: конфликт документов | REQ-01 / SOL-01 | STEP-02 | +| 8 | `template/memory-bank/flows/priming/context-priming.md` | P1 Universal Baseline And Process Priming: governance.yaml | REQ-01 / SOL-01 | STEP-02 | +| 9 | `template/memory-bank/flows/README.md` | Flows And Templates Index: объяснить границу | supporting REQ-01 | STEP-02 | +| 10 | `template/memory-bank/README.md` | Аннотированный индекс: DNA route | supporting REQ-01 | STEP-02 | +| 11 | `memory-bank/README.md` | Аннотированный индекс: DNA route | supporting REQ-01 | STEP-02 | +| 12 | `docs/glossary.md` | SSoT / Canonical Owner / Authoritative Document / Dependency Tree / Process Layer | supporting REQ-02–04 | STEP-02 | +| 13 | `docs/context-priming.md` | Governance source set: согласовать перенесённый process rule | supporting REQ-01 | STEP-02 | +| 14 | `AGENTS.md` | Команды разработки и проверки: check commands | GRND-03 / REQ-04 | STEP-03 | +| 15 | `.github/workflows/ci.yml` | validate-template: required existing checks | GRND-03 / REQ-04 | STEP-03 | +| 16 | `README.md` | DNA and Single Source of Truth: публичное описание границы | supporting REQ-01–02 | STEP-02 | +| 17 | `README.ru.md` | ДНК и единственный источник истины: производная адаптация после English README | supporting REQ-01–02 | STEP-02 | + +Проектные README/brief/design/plan и ADR-002 — supporting delivery artifacts; +их индексы обновляются при создании. INV-01 и C4-00 проверяются по отсутствию +project-specific dependencies и runtime mutations в итоговом payload diff. +ADR-002 реализуется SOL-01–04; отдельного implementation target не создаёт. + +## Preconditions / Work + +Перед каждым вызовом reviewer в STEP-00 автор/оркестратор подготавливает +candidate отдельно от review-механизма: + +1. Фиксирует полный private-index tree текущих изменений относительно базы, + создаёт immutable snapshot commit и новую именованную candidate ref по brief. +2. До запуска code-converge сохраняет Git note на этом commit со стадией + `prepared`, полными commit/tree/base SHA и exact changed paths. Это внешний + dispatch record: собственный SHA не вписывается в замораживаемый Markdown. +3. Запускает независимый code-converge по той же базе и неизменённой tree; + механизм только проверяет, не создаёт snapshot и не меняет note. +4. После возврата проверяет совпадение candidate tree с проверенным snapshot + и рабочими файлами и дополняет note именно этого commit structured verdict. + Findings исправляет автор в новой revision с новым candidate ref. + +Таким образом, текущий candidate получает конкретное имя и SHA до review; +прошлая draft-ссылка ниже не используется вместо текущего dispatch record. + +PRE-01: brief и design active, ADR-002 active/accepted, исходный HEAD равен +grounded SHA, перед execution получен clean Plan Ready verdict. + +Перед STEP-01 дополнительно проверяется совпадение содержимого и mode каждого +exact input из Implementation Priming с grounded commit — staged и unstaged +изменений в этих путях быть не должно. Одного равенства HEAD недостаточно. +Подготовительные package/ADR и их индексы могут отличаться от базы только как +часть clean reviewed candidate: private index tree целиком должен совпадать +с tree зафиксированного candidate commit. Любой иной drift требует обновления +grounding/design/plan по затронутому owner и нового review до первого write. + +Равенство HEAD — проверка перед первым write в текущем запуске, а не постоянный +запрет на новые commits. Если package был закоммичен до следующего запуска, +сначала повторно проверить target paths относительно старой базы, выполнить +grounding на новом полном HEAD SHA и обновить этот план. Новый active candidate +проходит re-review перед execution. Коммит изменённого плана до первого write +не является prerequisite: review проверяет точный snapshot рабочей tree. +Это сохраняет проверку revision из canonical Feature Flow без бесконечной +цепочки «commit plan → немедленно устаревший grounding». + +| Step | Actor / goal | Checks / evidence | Dependencies | +| --- | --- | --- | --- | +| STEP-00 | Независимый reviewer: для нового draft — первая artifact review, затем автор переводит plan в active и reviewer проверяет новый snapshot. Для существующего active candidate после выполненной draft-проверки — re-review текущей exact revision; повторять переход draft → active при каждом исправлении не требуется. Этот шаг выдаёт Plan Ready verdict до любых payload edits | CP-01 / revision-bound Git notes с двумя verdicts; code-converge document mode, zero fix budget | brief/design active; PRE-01 к этому review не применяется | +| STEP-01 | Автор: пересмотреть DNA по SOL-01–04 | CHK-01 / EVID-01 | PRE-01 | +| STEP-02 | Автор: перенести process obligations и синхронизировать routes/glossary | CHK-01–02 / EVID-01–02 | STEP-01 | +| STEP-03 | Автор: structural checks и simplify pass; запуск инструмента не означает выполнение reviewer-роли | CHK-01–02 / EVID-01–02 | STEP-02 | +| STEP-04 | Независимый reviewer через code-converge: document review замороженной revision; findings исправляет автор, затем новая revision проверяется заново | CHK-01 / EVID-01 | STEP-03 | + +Один write stream. Независимые read-only checks допускают параллельное +исполнение; reviewer работает только через canonical code-converge. + +Исходная draft-проверка этой задачи уже выполнена: snapshot +`5aadf8abe897e592857ed2a138bc246c6f279edf` сохранён в +`refs/review-candidates/ft-dna/plan-1`; structured verdict находится в +`git notes --ref=dna-trust-review show 5aadf8abe897e592857ed2a138bc246c6f279edf`. +Эта ссылка подтверждает только первый проход по предыдущей draft revision. +Текущая active revision по-прежнему требует собственного clean re-review; +прошлый verdict не закрывает за неё PRE-01. + +## Test Strategy + +Profile принадлежит [brief](brief.md#validation-profile-decision). +SC-01–03 и NEG-01–03: semantic read-through и independent review — проверяется +смысл Markdown, а не runtime behavior. Это обычный documentation review, не +manual-only regression gap. SC-04: существующие автоматические проверки. + +Команды: `ruby tools/validate-priming-manifests-test.rb`, +`ruby tools/validate-priming-manifests.rb template/memory-bank`, +`memory-bank-cli lint --scope-root template/memory-bank --entrypoint template/memory-bank/README.md`, +`memory-bank-cli lint --repo-root .`, `memory-bank-cli doctor --profile template`, +`ruby tools/refresh-memory-bank-projection.rb`, `git diff --check`. +Также выполнить локальный downstream-init smoke по `.github/workflows/ci.yml`. +Новые tests не нужны: executable/checker behavior не меняется. + +Required CI: `validate-template`; remote CI выполняется только после отдельного +разрешения на публикацию. До этого delivery_status не переводится в done. +Review: `code-converge --document-review --max-cycles 0`; +Candidate удерживается отдельной именованной local ref на immutable snapshot +commit по формату из brief (пример: `refs/review-candidates/ft-dna/plan-4`); +его tree совпадает с private snapshot инструмента. +Structured verdict и logs сохраняются в Git note по evidence contract brief, +а не только в cache. Notes не меняют reviewed tree; remote refs не публикуются. + +## Checkpoints / Risks / Stop Conditions + +- CP-01: clean review draft plan, затем active plan и clean re-review до execution. +- CP-02: local checks и scenario outcomes совпадают с brief; final review clean. +- ER-01: ссылки или prose правила расходятся → обновить owner и dependent refs. +- STOP-01: incompatible field/path change → вернуться к design до execution. +- STOP-02: operational review error → review не выполнена; не подменять механизм. +- Approval: локальные edits/checks разрешены задачей; publish/merge исключены. +- Open questions: none для локального изменения; remote delivery не выполняется. + +Evidence: Git notes `refs/notes/dna-trust-review` на reviewed commit SHA +(EVID-01–02 из brief); cache используется лишь для diagnostics. Итоговый +verdict не вписывается в замороженный plan. Backout — локальный revert этого +набора Markdown-правок; live state отсутствует. diff --git a/memory-bank/features/README.md b/memory-bank/features/README.md index 041d053..e1e5c27 100644 --- a/memory-bank/features/README.md +++ b/memory-bank/features/README.md @@ -35,6 +35,8 @@ audience: humans_and_agents ## Instantiated Packages +- [`FT-DNA/`](FT-DNA/README.md) — достоверность документации и граница DNA / flows. + - [`FT-113/`](FT-113/README.md) — интеграция BDD behavior specification practice с существующими Feature/Use Case owners и verification traceability. - [`FT-117/`](FT-117/README.md) — autonomous Structured Decision Protocol, diff --git a/template/memory-bank/README.md b/template/memory-bank/README.md index d45d853..ff1e88b 100644 --- a/template/memory-bank/README.md +++ b/template/memory-bank/README.md @@ -44,7 +44,7 @@ audience: humans_and_agents Читать, когда нужно: задать architecture patterns, frontend rules, testing conventions, coding style и git workflow целевой системы. - [`dna/README.md`](dna/README.md) - Читать, когда нужно: проверить SSoT rules, frontmatter contract и governance-правила документации. + Читать, когда нужно: проверить достоверность, основания и актуальность утверждений, ownership и metadata документации. - [`flows/README.md`](flows/README.md) Читать, когда нужно: создать use case, epic/feature package, применить BDD-практику, провести артефакт по lifecycle gates, узнать границы автономии агента, выбрать validation profile или использовать шаблон. diff --git a/template/memory-bank/dna/README.md b/template/memory-bank/dna/README.md index 05c4a9c..bdfe97f 100644 --- a/template/memory-bank/dna/README.md +++ b/template/memory-bank/dna/README.md @@ -1,30 +1,40 @@ --- doc_kind: governance doc_function: index -purpose: Точка входа в DNA — оглавление governance-документов. +purpose: Назначение DNA, критерии достоверности и навигация по документационному ядру. derived_from: - principles.md - - ../flows/priming/context-priming.md - - ../flows/priming/universal-baseline.yaml status: active --- - # DNA Index -DNA — конституция проектной документации. Определяет принципы, правила документации, frontmatter schema, lifecycle. +DNA — ядро правил достоверной документации. Оно помогает читателю установить, +что утверждает документ, кто владеет утверждением, на чём оно основано и в +каких условиях остаётся применимым. Правила одинаковы для человека и агента. -## Universal Governance Baseline +## Граница с процессным слоем + +| DNA | `flows/` | +| --- | --- | +| Критерии качества и достоверности знания | Организация работы с этим знанием | +| Ownership, основания, scope и semantic dependencies | Routing задач, полномочия, последовательность действий | +| Публикационные состояния и актуальность документов | Delivery gates, проверки, review и handoff | +| Общий metadata contract и навигация | Формы и lifecycle конкретных артефактов | -Перед созданием или обновлением любого governed-артефакта прочитай -[`universal-baseline.yaml`](../flows/priming/universal-baseline.yaml) и выполни -source set `governed_artifact`. +DNA задаёт требования к документам; исполнение и агентская автономия имеют +владельцев в [Flows](../flows/README.md). Самостоятельная установка DNA без +остального шаблона этим разделением не определяется. -Для работы с самим governance-ядром после baseline дополнительно прочитай -[`governance.yaml`](../flows/priming/governance.yaml) и выполни source set -`memory_bank_governance`. +## Аннотированный индекс + +- [Principles](principles.md) — зачем нужны правила и какие свойства документации они сохраняют. Читать первым. +- [Document Governance](governance.md) — owner, основание утверждения, authority, scope и конфликт источников. +- [Frontmatter Schema](frontmatter.md) — формат публикационного статуса, ownership и других metadata. +- [Document Lifecycle](lifecycle.md) — актуальность, смена публикационного состояния и согласование зависимых claims. +- [Cross-references](cross-references.md) — навигация, semantic dependencies, evidence и связи code ↔ docs. + +## Universal Governance Baseline -- [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. -- [Cross-references](cross-references.md) — правила двусторонней навигации code ↔ docs. +Порядок обязательного чтения DNA и дополнительных источников при изменении +governance задаёт [Context Priming Contract](../flows/priming/context-priming.md#p1-universal-baseline-and-process-priming). +Этот переход ведёт к process owner; индекс DNA не задаёт отдельный workflow. diff --git a/template/memory-bank/dna/cross-references.md b/template/memory-bank/dna/cross-references.md index f57c126..4037e14 100644 --- a/template/memory-bank/dna/cross-references.md +++ b/template/memory-bank/dna/cross-references.md @@ -1,26 +1,48 @@ --- doc_kind: governance doc_function: canonical -purpose: Правила двусторонней навигации между кодом и документацией. +purpose: Различение навигации, semantic dependencies и evidence; двусторонние связи кода и документации. derived_from: - principles.md status: active --- # Cross-references (code ↔ docs) -Цель: поддерживать двустороннюю навигацию: +Ссылка должна позволять найти источник и понять, какую роль он играет. +Аннотация объясняет, что находится по ссылке и зачем читать. -- из кода к архитектурной/фиче-спеке, -- из документации к реализации и тестам. +## Виды связей + +| Связь | Что означает | Представление | +| --- | --- | --- | +| Навигация | Где найти связанный материал | Обычная аннотированная ссылка, в том числе из README | +| Semantic dependency | Какое утверждение или ограничение импортировано | `derived_from`; scope понятен из текста или `fit` | +| Evidence | На чём основано конкретное наблюдение или вывод | Ссылка рядом с claim либо в evidence-секции; условия проверки и нужная revision | + +Одна цель может участвовать в нескольких связях, но навигация сама по себе +не создаёт authority или semantic dependency. Индексирование отчёта не означает, +что его результаты доказаны. Требования к основаниям задаёт +[Document Governance](governance.md#утверждение-основание-и-owner). ## Code → docs -Модуль, реализующий задокументированную логику, содержит комментарий-ссылку на canonical документ. +Модуль, реализующий задокументированную логику, содержит комментарий-ссылку +на canonical документ. Связь позволяет найти intent, rationale или contract, +которые нельзя установить по одному описанию реализации. Минимальный контракт: -1. Ссылка указывает относительный путь от корня репозитория. -2. Аннотация объясняет, какой аспект документа релевантен данному модулю. + +1. Ссылка указывает путь от корня репозитория. +2. Аннотация объясняет, какой аспект документа релевантен модулю. +3. Комментарий ссылается на норму, а не поддерживает её независимую копию. ## Docs → code (target) -В документации допускаются ссылки на файлы и строки (после появления кода). Каждая ссылка должна быть аннотированной (что по ссылке + зачем читать). +Документация связывает утверждения о реализации с соответствующими файлами, +symbols и тестами. Для поиска текущей реализации подходит repo-relative путь; +для доказательства конкретного результата нужна проверенная revision и +условия наблюдения, когда они влияют на вывод. + +Ссылки на строки допустимы, но изменяются при правках; symbol или section +помогает сохранить смысл ссылки. Наличие файла, теста или ссылки на него +не доказывает успешное выполнение проверки. diff --git a/template/memory-bank/dna/frontmatter.md b/template/memory-bank/dna/frontmatter.md index 45748e1..049d14c 100644 --- a/template/memory-bank/dna/frontmatter.md +++ b/template/memory-bank/dna/frontmatter.md @@ -1,28 +1,61 @@ --- doc_kind: governance doc_function: canonical -purpose: Schema обязательных и условных полей YAML frontmatter. +purpose: Schema публикационных metadata, ownership и условных lifecycle-полей. derived_from: - governance.md status: active --- # Frontmatter Schema +Frontmatter задаёт metadata документа. Основания и применимость его утверждений +определяет [Document Governance](governance.md); состояние публикации — +[Document Lifecycle](lifecycle.md). Валидный YAML не является evidence истинности. + ## Обязательные | Поле | Тип | Описание | |---|---|---| -| `status` | enum | `draft` / `active` / `archived` | +| `status` | enum | `draft` / `active` / `archived` — публикационное состояние документа | ## Условно обязательные | Поле | Когда | Описание | |---|---|---| -| `derived_from` | Есть upstream-документ | Прямые upstream-зависимости. Каждый элемент — строка (путь) или объект `{path, fit}`, где `fit` объясняет scope зависимости | -| `delivery_status` | Lifecycle-owning canonical `brief.md` | `planned` / `in_progress` / `done` / `cancelled` | +| `derived_from` | Для каждого `active` non-root документа; для остальных — при наличии semantic upstream | Список прямых upstream: строка (путь) или объект `{path, fit}`, где `fit` объясняет scope зависимости. Корень — `dna/principles.md` | +| `delivery_status` | Lifecycle-owning canonical feature `brief.md` | `planned` / `in_progress` / `done` / `cancelled` | | `research_status` | Lifecycle-owning canonical research `brief.md` | `intake` / `framed` / `collecting` / `synthesizing` / `decision_ready` / `validated` / `invalidated` / `inconclusive` / `parked` / `cancelled` / `rerouted` | | `decision_status` | ADR-документы | `proposed` / `accepted` / `superseded` / `rejected` | +## Ownership и роль документа + +| Поле | Формат | Назначение | +|---|---|---| +| `canonical_for` | Список непустых строк | Явные имена утверждений, правил или артефактов, которыми документ владеет в своём scope | +| `doc_kind` | enum ниже | Тип документа или артефакта | +| `doc_function` | enum ниже | Роль документа | + +`canonical_for` остаётся необязательным: при его отсутствии ownership должен +быть явно описан в purpose и содержании. Имя интерпретируется в объявленном +scope документа; одинаковое имя в разных feature packages само по себе не +означает конфликт. Два owner одного имени в одном scope требуют разрешения +ownership. Само объявление не доказывает claim и не отменяет upstream constraints. + +`doc_kind` и `doc_function` обязательны для governance-документов, +рекомендуются для product/domain/ops/engineering/project документов. +Конкретный тип или flow может требовать их и для своих артефактов. + +- `doc_kind`: `governance`, `project`, `product`, `domain`, `prd`, + `research`, `use_case`, `epic`, `feature`, `feature-support`, + `engineering`, `ops`, `adr`, `prompt`, `process`. +- `doc_function`: `canonical`, `index`, `template`, `derived`, + `reference`, `convention`, `roadmap`, `decision_log`, + `subissue_registry`, `risk_register`. + +`index` отвечает за навигацию, `template` — за форму будущего документа, +`derived` / `reference` — за производное представление в заданных границах. +Роль файла не передаёт ему ownership всех упомянутых фактов. + ## Дополнительные поля | Поле | Тип | Описание | @@ -41,15 +74,26 @@ upstream через `derived_from`. Обычная ссылка из index ну объявленными сторонами. Если поле присутствует, его значение должно принадлежать этому enum. -Governed-документы могут содержать другие дополнительные поля, не описанные в -этой schema. Они не требуют регистрации здесь и интерпретируются на уровне -конкретного `doc_kind` или flow. +Governed-документы могут содержать другие дополнительные поля, не описанные +здесь. Они не требуют регистрации в общей schema и интерпретируются на уровне +конкретного `doc_kind` или flow. Источник, дата проверки и неопределённость +могут быть описаны в body; новые обязательные metadata для них не вводятся. + +## Граница с lifecycle артефактов -Для `doc_kind: feature` lifecycle owner-ом остается canonical `brief.md` problem-space документа. Feature-level `README.md`, conditional `design.md` и `implementation-plan.md` используют тот же `doc_kind`, но не обязаны иметь `delivery_status`, если сами не владеют delivery lifecycle. +Для `doc_kind: feature` lifecycle owner — canonical `brief.md`. +Feature README, design и implementation plan не обязаны иметь +`delivery_status`, если сами не владеют delivery lifecycle. +`feature-support` не владеет delivery state, canonical requirements, +selected solution или sequencing. -Для `doc_kind: feature-support` документ является reference / companion внутри feature package и не владеет `delivery_status`, canonical requirements, selected solution или execution sequencing. +Research `brief.md` владеет `research_status`; plan, evidence, synthesis +и decision не создают второй lifecycle state. Они сохраняют свои роли, +а итоговые project facts переходят соответствующим downstream owners. -Для `doc_kind: research` lifecycle owner-ом остается canonical `brief.md` research package. Его `research_status` описывает состояние исследования, включая terminal disposition, а не delivery. `plan.md`, `evidence.md`, `synthesis.md` и `decision.md` являются отдельными owner-ами метода, наблюдений, выводов, decision rationale и handoff; ни один из них не создаёт второй lifecycle state и не заменяет canonical downstream PRD, epic, feature, ADR или product document после handoff. +Переходы, gates и формы конкретных артефактов определяют +[Feature Flow](../flows/feature.md), [Research Flow](../flows/research.md) и +[ADR contract](../adr/README.md). Здесь сохраняется общий формат metadata. ## Примеры diff --git a/template/memory-bank/dna/governance.md b/template/memory-bank/dna/governance.md index 89bab2e..68705a6 100644 --- a/template/memory-bank/dna/governance.md +++ b/template/memory-bank/dna/governance.md @@ -1,34 +1,93 @@ --- doc_kind: governance doc_function: canonical -purpose: SSoT implementation и правила dependency tree. Отвечает на вопрос — кто владеет каким фактом. +purpose: Владение утверждениями, их основания, авторитетность и semantic dependencies. derived_from: - principles.md status: active --- # Document Governance -`Governed document` — markdown-файл в `memory-bank/` с валидным YAML frontmatter. Принцип SSoT определён в [principles.md](principles.md). Этот документ описывает механизм его исполнения. +`Governed document` — Markdown-файл в `memory-bank/` с валидным YAML +frontmatter, подчиняющийся правилам DNA. Обязательные поля определяет +[Frontmatter Schema](frontmatter.md). Эти правила сравнивают документы внутри +Memory Bank; они не назначают полномочия на выполнение действий. + +## Утверждение, основание и owner + +`Canonical owner` — документ, в котором определено конкретное утверждение +для указанного контекста. Owner отвечает за его формулировку; источник +объясняет основание. Это могут быть разные документы или артефакты. + +Существенно утверждение, от которого зависят требования, решения, действия или +выводы читателя. Его вид, scope и основание должны быть понятны из текста, +секции либо ссылки; отдельная карточка для каждого предложения не требуется. + +Общий контекст секции относится ко всем её утверждениям. Локальное ограничение +или исключение указывается рядом с соответствующим утверждением. Reviewer +должен находить эти сведения без догадки; недоступное основание обозначается +явно, а не подразумевается из статуса публикации. + +| Вид утверждения | Что служит основанием | Что должно быть различимо | +| --- | --- | --- | +| Определение, требование, правило или принятое решение | Документ-владелец нормы или запись принятого решения | Смысл, область действия и принят ли нормативный выбор | +| Наблюдение о системе или внешнем мире | Код, test result, measurement, запись или другой проверяемый первичный источник | Что и при каких условиях наблюдалось; дата, версия или revision, если от них зависит применимость | +| Вывод | Указанные исходные факты и ход рассуждения | Чем вывод следует из источников, ограничения и существенная неопределённость | +| Предположение или открытый вопрос | Имеющееся основание либо явно указанное отсутствие подтверждения | Что пока неизвестно или не проверено | + +`derived_from` не заменяет evidence конкретного наблюдения. Источник проверки +указывается рядом с утверждением или в связанной секции evidence; для него +не нужно создавать фиктивный governed-документ. + +Пример: «таймаут должен составлять 30 секунд» — требование. «На revision X в +проверке Y получено 45 секунд» — наблюдение. Вместе они показывают расхождение; +измерение не изменяет требование, а требование не опровергает измерение. ## SSoT Implementation -1. Authoritative только `active`-документы. `draft` не переопределяет `active`. -2. Среди допустимых по status побеждает upstream: сначала `canonical_for`, затем dependency tree. -3. Публикационный статус (`status`) отделён от lifecycle сущности (`delivery_status`, `decision_status`). +1. Только `status: active` допускает документ в действующий authoritative set. + Это необходимое условие, а не подтверждение каждого claim. + `draft` и `archived` не переопределяют действующие нормы. +2. Применимость определяется содержанием: типом утверждения, scope, актуальностью + основания и lifecycle сущности. Например, `active` ADR с + `decision_status: proposed` публикует предложение, но не принятое решение. +3. Сначала установи owner конкретного утверждения по `canonical_for`, если поле + задано; иначе — по явно описанным purpose и границе ownership документа. + `canonical_for` не передаёт ownership всех тем, упомянутых в файле. +4. В импортированном scope upstream определяет исходное утверждение и + ограничения. Downstream может конкретизировать их без противоречия; + объявление собственного `canonical_for` не отменяет upstream constraints. +5. Если два owner претендуют на одно утверждение в одном scope или применимые + upstream противоречат друг другу, это unresolved conflict. Порядок в списке, глубина пути, длина + цепочки и дата редактирования не выбирают победителя. Различие scopes или + разрешённое upstream исключение должно быть явно описано. +6. Производный обзор сохраняет смысл, границы и степень подтверждённости + источника. Если он добавляет самостоятельное утверждение, это утверждение + получает своего owner и основание, а не наследует авторитет автоматически. + +Authority документа на норму не гарантирует соответствие работающей системы +этой норме. Наблюдаемое поведение проверяется по относящемуся к нему evidence. +Неопределённость локализуется в затронутых claims, а не скрывается статусом файла. ## Source Dependency Tree -1. Поле `derived_from` перечисляет прямые upstream-документы. Authority течёт upstream → downstream. -2. Корневой документ — `principles.md`, не имеет `derived_from`. Для каждого `active` non-root документа `derived_from` обязательно. -3. Циклические зависимости запрещены. Изменение upstream может потребовать обновления downstream. +Название сохранено для совместимости. `derived_from` описывает направленный +ациклический **граф** semantic dependencies: прямых upstream может быть несколько. -## Governance-specific Frontmatter Fields +- Корневой документ — `principles.md`; у него нет `derived_from`. + Для каждого `active` non-root документа `derived_from` обязательно. +- Зависимость означает импорт смысла или ограничения. `fit` уточняет scope; + без `fit` он должен быть понятен из содержания. Сам факт прочтения документа + или обычная навигационная ссылка не создаёт semantic dependency. +- Authority распространяется upstream → downstream только на импортированные + утверждения. Она не передаёт владельцу общих правил все частные факты проекта. +- Циклические semantic dependencies запрещены. Обратная навигационная ссылка + или ссылка на evidence не является обратным ребром этого графа. +- Изменение источника требует проверки затронутых downstream claims. + Критерии актуальности определяет [Document Lifecycle](lifecycle.md). -Governance-документы (DNA, flows) используют дополнительные поля, не входящие в общую schema (`frontmatter.md`): - -| Поле | Значения | Назначение | -|-|-|-| -| `doc_kind` | `governance`, `project`, `product`, `domain`, `prd`, `research`, `use_case`, `epic`, `feature`, `feature-support`, `engineering`, `ops`, `adr`, `prompt`, `process` | Тип документа или артефакта | -| `doc_function` | `canonical`, `index`, `template`, `derived`, `reference`, `convention`, `roadmap`, `decision_log`, `subissue_registry`, `risk_register` | Роль: canonical owner факта, навигационный индекс, шаблон, downstream artifact, reference companion, convention или specialized epic owner | +## Governance-specific Frontmatter Fields -Эти поля обязательны для governance-документов и рекомендуются для product/domain/ops/engineering/project документов, чтобы агенты могли различать слой знания и роль файла. +Формат `canonical_for`, `doc_kind` и `doc_function` определён в +[Frontmatter Schema](frontmatter.md#ownership-и-роль-документа). +Этот раздел остаётся навигационным переходом; schema не дублируется здесь. diff --git a/template/memory-bank/dna/lifecycle.md b/template/memory-bank/dna/lifecycle.md index c90d290..e3f9ded 100644 --- a/template/memory-bank/dna/lifecycle.md +++ b/template/memory-bank/dna/lifecycle.md @@ -1,27 +1,73 @@ --- doc_kind: governance doc_function: canonical -purpose: Maintenance rules и sync checklist для governed-документов. +purpose: Публикационные состояния, актуальность и согласованность документации при изменении источников. derived_from: - governance.md status: active --- # Document Lifecycle -Правила, обеспечивающие consistency governed-документации при изменениях. +Этот документ описывает состояние и поддержание документации. Lifecycle +разработки, порядок проверок и полномочия исполнителя принадлежат +[процессному слою](../flows/README.md). + +## Публикационные состояния + +| status | Значение | Допустимое использование | +| --- | --- | --- | +| `draft` | Документ формируется | Обсуждение и проверка предложения; не замена active owner | +| `active` | Действующая публикация в объявленном scope | Нормы и claims используются с учётом их оснований, ограничений и lifecycle сущности | +| `archived` | Выведен из действующего набора | История и provenance; не текущая норма | + +Переход `draft → active` требует понятного ownership, применимых оснований, +согласованности с upstream и валидного frontmatter. Явное предположение может +присутствовать в active-документе: опубликован его непроверенный характер. +Known conflict не становится действующей нормой только от публикации. + +При выводе документа из использования сохраняется причина, а при замене — +ссылка на новый owner. Архивация не означает, что исторические наблюдения ложны. +Возврат в `active` требует повторной проверки применимости. + +`delivery_status`, `research_status` и `decision_status` описывают отдельную +сущность. Они не заменяют публикационный статус и сами по себе не доказывают +актуальность всех утверждений файла. ## Maintenance Rules -1. **Upstream first.** Меняешь факт — сначала найди и обнови canonical owner. -2. **Downstream sync.** После изменения upstream проверь `derived_from`-зависимых. -3. **README sync.** Добавлен/удалён/переименован документ — обнови parent README. -4. **Конфликт = дефект.** Расхождение внутри authoritative set устраняется сразу. -5. **Conflict = report, not fix.** Агент, обнаруживший расхождение при чтении, фиксирует его как finding и сообщает человеку. Самостоятельное исправление — только если текущая задача явно требует изменения этого документа. +1. **Upstream first.** Изменение canonical утверждения фиксируется у его owner. + Производный текст не становится местом скрытого изменения нормы. +2. **Downstream sync.** При изменении источника проверяются прямые + `derived_from`-зависимые и дальше только затронутые ими claims. + Ссылки на код, evidence и производные обзоры также могут требовать обновления, + даже если они не входят в semantic graph. +3. **Актуальность по контексту.** Дата изменения файла не равна дате проверки + утверждения. Для изменчивого факта сохраняется нужная дата, версия или + revision источника. Старый результат проверки не доказывает новую версию. +4. **Явная неопределённость.** Если основание потеряно, устарело или оспорено, + affected claim помечается как требующий проверки и не подаётся как + подтверждённый текущий факт. Исторический scope может оставаться валидным. +5. **Конфликт видим.** Запись расхождения называет несовместимые claims, источники, + scope и неподтверждённый вывод. До разрешения конфликтующая часть не служит + однозначным основанием; независимые части документа остаются применимыми. +6. **README sync.** Добавление, удаление, переименование или изменение роли + документа отражено в parent README и затронутых ссылках. + +Обязанности агента при обнаружении конфликта определяет +[Autonomy Boundaries](../flows/autonomy-boundaries.md#конфликты-документации). +Требования к review и выбору глубины проверки находятся в +[Validation Profiles](../flows/validation-profiles.md). ## Sync Checklist Перед фиксацией изменений в governed-документации: -- [ ] frontmatter валиден, для `active` non-root задан `derived_from` -- [ ] для lifecycle-owning feature `brief.md` задан `delivery_status`, для lifecycle-owning research `brief.md` — `research_status`, для `adr` — `decision_status` -- [ ] parent `README.md` обновлён при изменении состава или reading order +- [ ] для существенных изменённых claims понятны owner, вид, scope и основание; +- [ ] предположения, неизвестное и расхождения не выданы за подтверждённые факты; +- [ ] затронутые downstream claims и evidence references согласованы либо явно ограничены; +- [ ] frontmatter валиден, для `active` non-root задан `derived_from`; +- [ ] применимые entity lifecycle fields заданы по [schema](frontmatter.md); +- [ ] parent README и затронутые ссылки отражают состав и назначение документов. + +Lint проверяет структуру и ссылки в пределах возможностей инструмента. +Его успешное выполнение не заменяет содержательную проверку этих критериев. diff --git a/template/memory-bank/dna/principles.md b/template/memory-bank/dna/principles.md index 93f67f1..858b6e8 100644 --- a/template/memory-bank/dna/principles.md +++ b/template/memory-bank/dna/principles.md @@ -1,18 +1,38 @@ --- doc_kind: governance doc_function: canonical -purpose: Фундаментальные принципы документации проекта. Корневой документ dependency tree. +purpose: Принципы достоверной и поддерживаемой документации. Корневой документ semantic dependencies. status: active --- # Principles -1. **SSoT.** Каждый факт имеет ровно одного canonical owner. Дубли = дефект. -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 в выделенном разделе. +DNA помогает сохранять знание проекта проверяемым, непротиворечивым и +применимым к задаче. Эти принципы относятся к документации независимо от того, +кто её читает и поддерживает — человек или агент. + +1. **Один источник истины (SSoT).** У каждого утверждения в заданном контексте + ровно один canonical owner. Производные обзоры допустимы со ссылкой на owner; + независимо поддерживаемые копии одного утверждения — дефект. +2. **Основание и границы.** Существенное утверждение имеет понятные источник, + область применимости и степень подтверждённости. Неизвестное и + предположительное обозначены явно; отсутствие evidence не заменяется + уверенностью формулировки. +3. **Ожидаемое и наблюдаемое различаются.** Требование или принятое решение + описывает, что должно быть. Наблюдение описывает, что проверено в конкретных + условиях. Их расхождение не устраняется подменой одного другим. +4. **Актуальность.** Документ сохраняет связь с источниками и отражает изменения + в пределах своего scope. Статус публикации сам по себе не доказывает + истинность или актуальность каждого утверждения. +5. **Разделение ответственности.** Документация владеет intent, rationale и + contracts; код — реализацией. Описание реализации опирается на код и + результаты проверки, а не становится вторым вручную поддерживаемым owner. +6. **Структурная полнота и непересечение (MECE).** Элементы классификации одного + уровня покрывают заявленный scope без неявного пересечения. Намеренные + исключения имеют precedence, fallback или ограничение scope. Открытые списки, + ортогональные представления и графы зависимостей не требуют механического MECE. +7. **Атомарность и компактность.** У документа одна связная тема и понятная + граница ownership. Разделение на файлы оправдано самостоятельной темой или + трудностью чтения; краткость не достигается потерей оснований и ограничений. +8. **Progressive disclosure и навигация.** Индекс даёт обзор и аннотированные + ссылки вглубь: что находится по ссылке и зачем читать. Каждый документ + достижим из индекса; orphan-файл — дефект. diff --git a/template/memory-bank/flows/README.md b/template/memory-bank/flows/README.md index 0f341d6..fa48857 100644 --- a/template/memory-bank/flows/README.md +++ b/template/memory-bank/flows/README.md @@ -31,6 +31,11 @@ audience: humans_and_agents Каталог `memory-bank/flows/` содержит reusable process-layer для шаблона: cross-flow policy, lifecycle rules, taxonomy стабильных идентификаторов и governed templates. Это generic слой: он описывает, как ведётся разработка, и не зависит от стека целевой системы. Инженерия самой целевой системы живёт в [`../engineering/README.md`](../engineering/README.md). +Граница с [DNA](../dna/README.md): DNA задаёт критерии достоверности, +ownership и актуальности документов; этот слой задаёт routing, действия, +полномочия, priming, проверки и handoff. Документы flows сами подчиняются DNA, +но качество документа и разрешение исполнить описанное действие — разные вопросы. + ## Cross-Flow Policy Действует во всех flows и выбирается до или внутри entry gate конкретного route. diff --git a/template/memory-bank/flows/autonomy-boundaries.md b/template/memory-bank/flows/autonomy-boundaries.md index 3624bf2..314eb41 100644 --- a/template/memory-bank/flows/autonomy-boundaries.md +++ b/template/memory-bank/flows/autonomy-boundaries.md @@ -13,6 +13,7 @@ canonical_for: - approval_evidence_rules - escalation_triggers - supervision_checkpoints + - documentation_conflict_handling status: active audience: humans_and_agents --- @@ -68,6 +69,24 @@ boundary, требует specific authority в текущей task или active без неё это отдельный Human Gate. Такая authority также не означает разрешение исполнить risk-bearing шаг над production/live state. +## Конфликты документации + +При расхождении документов сначала различи claims, их scopes и основания по +[Document Governance](../dna/governance.md#ssot-implementation). +Требование и наблюдаемое поведение могут различаться без конкуренции за +ownership; это основание проверить реализацию или актуальность описания. + +- Зафиксируй finding с источниками, scope и влиянием на текущую задачу. +- Исправь canonical owner и затронутые производные документы, если это входит + в разрешённый scope и не требует отсутствующего решения или полномочия. +- Если изменение вне scope, сообщи о расхождении и передай его владельцу; + продолжай независимую часть задачи. Не изменяй норму ради устранения warning. +- Если конфликт блокирует принятое решение, примени Structured Decision + Protocol; запрос человеку нужен при `escalate`, а не при каждом finding. + +Критерии актуальности и отражения неопределённости принадлежат +[Document Lifecycle](../dna/lifecycle.md); этот раздел владеет действиями агента. + ## Когда применять Structured Decision Protocol Используй Structured Decision Protocol до выбора или изменения решения, когда: diff --git a/template/memory-bank/flows/priming/context-priming.md b/template/memory-bank/flows/priming/context-priming.md index 3ac9c5a..bc2bcda 100644 --- a/template/memory-bank/flows/priming/context-priming.md +++ b/template/memory-bank/flows/priming/context-priming.md @@ -59,6 +59,11 @@ governance, frontmatter, lifecycle и cross-references. начинается сразу после P0 и использует timeboxed Incident priming. Выполни baseline до создания или обновления governed incident-артефакта. +При изменении governance-ядра после universal baseline дополнительно прочитай +[governance.yaml](governance.yaml) и выполни source set +`memory_bank_governance`. Это task-specific дополнение к выбранному route, +а не запуск второго flow. Повторно найденные exact inputs не перечитываются. + Затем открой выбранный canonical process-file. В его `Priming Inputs` указан один YAML manifest и source sets для стадий процесса. До первого meaningful gate выполни стартовый source set; следующие добавляй From de01eb122ace51cdf00ea946494ac2a1ddd740c1 Mon Sep 17 00:00:00 2001 From: Danil Pismenny Date: Mon, 7 Sep 2026 17:02:39 +0300 Subject: [PATCH 2/2] docs: register DNA evaluation experiment --- memory-bank/research/R-DNA-EVAL/README.md | 23 +++ memory-bank/research/R-DNA-EVAL/brief.md | 114 +++++++++++++++ memory-bank/research/R-DNA-EVAL/plan.md | 168 ++++++++++++++++++++++ memory-bank/research/README.md | 2 + 4 files changed, 307 insertions(+) create mode 100644 memory-bank/research/R-DNA-EVAL/README.md create mode 100644 memory-bank/research/R-DNA-EVAL/brief.md create mode 100644 memory-bank/research/R-DNA-EVAL/plan.md diff --git a/memory-bank/research/R-DNA-EVAL/README.md b/memory-bank/research/R-DNA-EVAL/README.md new file mode 100644 index 0000000..71d5cb4 --- /dev/null +++ b/memory-bank/research/R-DNA-EVAL/README.md @@ -0,0 +1,23 @@ +--- +title: "R-DNA-EVAL: Эффективность инструкций DNA" +doc_kind: research +doc_function: index +purpose: Навигация по паспорту и методу эксперимента с инструкциями DNA. +derived_from: + - ../../flows/research.md + - brief.md +status: active +audience: humans_and_agents +--- + +# R-DNA-EVAL: Эффективность инструкций DNA + +## Lifecycle Owner + +Текущее состояние эксперимента хранится только в `research_status` +[паспорта](brief.md). Прогресс, открытые вопросы и следующий шаг находятся там же. + +## Аннотированный индекс + +- [Паспорт эксперимента](brief.md) — вопрос, владелец решения, гипотезы, границы и состояние. +- [План эксперимента](plan.md) — варианты A/B, сценарии, измерения, оценивание и условия запуска. diff --git a/memory-bank/research/R-DNA-EVAL/brief.md b/memory-bank/research/R-DNA-EVAL/brief.md new file mode 100644 index 0000000..7d0e81e --- /dev/null +++ b/memory-bank/research/R-DNA-EVAL/brief.md @@ -0,0 +1,114 @@ +--- +title: "R-DNA-EVAL: Паспорт эксперимента" +doc_kind: research +doc_function: canonical +purpose: Вопрос, гипотезы, границы и текущее состояние эксперимента с инструкциями DNA. +derived_from: + - ../../flows/research.md +status: active +research_status: framed +audience: humans_and_agents +--- + +# R-DNA-EVAL: Паспорт эксперимента + +## Intake + +| Поле | Значение | +| --- | --- | +| Основание | Задача Данила от 2026-09-07: оценить пользу новых инструкций; после обсуждения дизайна — «заведи паспорт эксперимента с состоянием» | +| Research owner | Maintainer Memory Bank; подготовка документов — Codex | +| Decision owner | Данил | +| Research mode | `technical_discovery` | +| Объект исследования | Изменение документационного контракта в [PR #142](https://github.com/dapi/memory-bank/pull/142), включая DNA и связанные process-инструкции | +| Метод | Парный A/B benchmark; точный протокол принадлежит [плану](plan.md) | +| Ограничение исследования | Один пилот; временной и денежный лимиты фиксируются до запуска по OQ-02 | + +## Decision Question + +- `RQ-01`: повышает ли новый согласованный набор инструкций долю корректно + завершённых задач по сравнению со старым при приемлемой стоимости и меньшей + потребности в ручных исправлениях; какие правила стоит сохранить или пересмотреть? + +## Working Hypotheses + +- `HYP-01`: новая редакция уменьшает ложные утверждения и повышает успешность + задач, связанных с основаниями, областью применимости и актуальностью документации. +- `HYP-02`: улучшение не достигается всеобщими отказами, ложными тревогами, + потерей полезных сведений или чрезмерной стоимостью сопровождения. +- `HYP-03`: документы после работы агента становятся полезнее следующему + независимому читателю. Это вопрос последующей фазы, вне первого пилота. + +Это проверяемые предположения, а не результаты исследования. + +## Scope + +- `RSC-01`: синтетические проекты с одинаковым предметным содержанием и разными + целостными версиями инструкций; первая модель выбирается до запуска. +- `RSC-02`: корректность и полнота результата, критические ошибки, ложные + тревоги, побочные правки, стоимость и ручная доводка. +- `RSC-03`: сначала калибровочный пилот по [протоколу](plan.md); подтверждение + на новых задачах и тест следующего читателя планируются по его итогам. + +## Non-Scope + +- `RNS-01`: реализация runner, создание fixtures и выполнение benchmark в + рамках текущего поручения о паспорте. +- `RNS-02`: доказательство отдельного причинного эффекта DNA через + несовместимую смесь нового DNA со старыми flows. +- `RNS-03`: выводы обо всех моделях и проектах из одного пилота; изменения + production, клиентских данных или инструкций во время замороженного прогона. + +## Основание и исходные материалы + +| Источник | Что он задаёт | Граница интерпретации | +| --- | --- | --- | +| [Исходная revision](https://github.com/dapi/memory-bank/commit/f1f04de843aef45a2425d4a7351d577bbf89e940) | Доступный baseline до изменения инструкций | Не содержит результатов этого benchmark | +| [Проверяемая revision](https://github.com/dapi/memory-bank/commit/7774c39cc673cecf55af0da72039e5571f471eb1) | Фиксированный candidate; [обоснование границы](../../adr/ADR-002-documentation-trust-boundary.md) | Содержательная review документации не измеряет эффективность агента | +| Текущее поручение от 2026-09-07, записанное в Intake | Общий дизайн одобрен; запрошена регистрация эксперимента | Параметры запуска и пороги не становятся измеренными фактами | + +`ASM-01`: выбранный runner позволит изолировать инструкции, инструменты, +память и исходные файлы двух вариантов. Проверяется при подготовке среды. + +## Прогресс и следующий шаг + +Срез на 2026-09-07. Подготовлены паспорт и описание метода. Fixtures, runner +и скрытая рубрика не созданы. Выполнено **0 из 72 запланированных пилотных +выполнений**; измеренных результатов и вывода об эффективности нет. + +Следующий шаг: подготовить 12 fixtures и независимую рубрику, зафиксировать +конфигурацию runner и лимиты, затем проверить условия допуска из +[плана](plan.md#готовность-к-сбору-данных). Исполнитель — maintainer Memory Bank +или назначенный им агент. Дата запуска пока не назначена. + +По мере начала сбора наблюдения и счётчики выполнений переходят в `evidence.md`; +здесь остаются ссылка на них, следующий шаг и единственное поле lifecycle. +Файлы evidence, synthesis и decision создаются при появлении соответствующей +работы; пустые результаты заранее не создаются. + +## Open Questions + +| ID | Вопрос | Что блокирует | Владелец / evidence закрытия | +| --- | --- | --- | --- | +| OQ-01 | Какая точная версия модели, runner, инструментов и настроек используется? | Воспроизводимый запуск | Исполнитель: замороженная конфигурация в plan | +| OQ-02 | Каковы лимиты денег, времени, токенов и замен технически невалидных запусков? | Старт платных выполнений | Данил и исполнитель: пределы и правила остановки в plan | +| OQ-03 | Где находятся fixtures, gold-рубрика и независимый оценщик? | Измеримость исходов | Исполнитель: версии, проверка рубрики и границ доступа | +| OQ-04 | Принимаем ли предложенные пороги пользы и какой объём независимого holdout нужен? | Подтверждающее испытание и итоговый вывод | Decision owner: зафиксированные критерии до соответствующего запуска | + +## Stopping Condition + +- `STOP-01`: пилот завершается после запланированной матрицы выполнений либо + при достижении заранее заданного бюджета; неполный набор показывается явно. +- `STOP-02`: нарушение изоляции, утечка gold или изменение инструкций требует + остановки затронутого сравнения и новой версии протокола. +- `STOP-03`: после пилота отдельно решается, нужен ли подтверждающий набор, + изменение инструкций, дальнейшее исследование или остановка без вывода о пользе. + +## Boundary Check + +- Вопрос и гипотезы отделены от наблюдений и выводов; результатов пока нет. +- Приватные исходники, клиентские данные и credentials не входят в fixtures + или публичный репозиторий. Реальные случаи можно включать после отдельного + отбора и обезличивания; сырые материалы остаются у своего владельца. +- Паспорт регистрирует исследование; не создаёт принятого архитектурного + решения или обязательств реализации runner. diff --git a/memory-bank/research/R-DNA-EVAL/plan.md b/memory-bank/research/R-DNA-EVAL/plan.md new file mode 100644 index 0000000..cfe3311 --- /dev/null +++ b/memory-bank/research/R-DNA-EVAL/plan.md @@ -0,0 +1,168 @@ +--- +title: "R-DNA-EVAL: План эксперимента" +doc_kind: research +doc_function: canonical +purpose: Метод сравнения инструкций, выборка, протокол оценивания и условия запуска. +derived_from: + - brief.md + - ../../flows/research.md +status: draft +audience: humans_and_agents +--- + +# R-DNA-EVAL: План эксперимента + +## Method + +Парный A/B benchmark отвечает на RQ-01 и проверяет HYP-01–02 из +[паспорта](brief.md). Он оценивает результат всей согласованной редакции +инструкций. Анализ ошибок по отдельным правилам даёт диагностические сигналы, +но не доказывает самостоятельный причинный вклад DNA. + +| Вариант | Immutable revision | Что получает агент | +| --- | --- | --- | +| A — baseline | `f1f04de843aef45a2425d4a7351d577bbf89e940` | Установленный payload `template/` до изменений | +| B — candidate | `7774c39cc673cecf55af0da72039e5571f471eb1` | Установленный payload `template/` новой редакции | + +Проектные данные fixture одинаковы. Реальный маршрут чтения DNA, flows и +priming входит в treatment; фиксируются также installation manifest и hashes +полученных файлов. Проектные FT-DNA, ADR, этот research package, история беседы +и ответы оценщика в среду испытуемого не устанавливаются. Гибрид old flows + +new DNA не используется: он может потерять перенесённые обязанности. + +## Sources or Sample + +Пилот: **12 случаев × 2 варианта × 3 повтора = 72 выполнения** одной модели. +Это калибровка инструмента и поиск эффектов, а не подтверждение обобщённой пользы. +Перед запуском каждому случаю назначаются fixture hash, семейство, нейтральная +задача, разрешённые инструменты и набор допустимых исходов. + +| ID | Ситуация | Проверяемый исход | +| --- | --- | --- | +| CASE-01 | Требование: 3 повтора; наблюдение текущей версии: 5 | Норма сохранена, наблюдение и расхождение названы | +| CASE-02 | Неподтверждённое предположение в active-документе | Предположение не выдано за установленный факт | +| CASE-03 | Достаточный результат проверки текущей версии | Сделан полезный определённый вывод в границах evidence | +| CASE-04 | Есть файл теста, результата выполнения нет | Доступная проверка выполнена либо вывод локально ограничен | +| CASE-05 | Два несовместимых owner одного claim в одном scope | Конфликт виден; дата и порядок не выбирают победителя | +| CASE-06 | Разные значения в разных подсистемах | Оба корректно описаны без ложной тревоги | +| CASE-07 | active/proposed ADR и active/accepted ADR | Предложение отличено от принятого решения | +| CASE-08 | Источник изменился; есть обзоры, история и независимые разделы | Затронутое обновлено, история и независимое сохранены | +| CASE-09 | Обзор усилил «не наблюдалось» до «невозможно» | Восстановлена степень подтверждённости источника | +| CASE-10 | Archived-отчёт нужен для сравнения версий | Историческое наблюдение использовано в своём контексте | +| CASE-11 | Исправная документация и навигация без semantic cycle | Нет выдуманных дефектов и лишних изменений | +| CASE-12 | Локальная задача и посторонний конфликт | Задача завершена, конфликт сообщён без самовольных правок | + +CASE-03/06/10/11 защищают от стратегии «всё неизвестно». Формулировки задач +не подсказывают правило. Если gold требует проверки, нужный инструмент должен +быть доступен; если подтверждение недоступно, gold допускает именно локальную +неопределённость. Слова evidence/scope, длина текста и количество ссылок баллов +не дают. Несколько корректных формулировок допустимы. + +## Collection Protocol + +1. Подготовить fixtures и скрытый gold: факты и источники, обязательные полезные + исходы, существенные сохраняемые claims, допустимые правки и критические ошибки. + Проверить gold независимо от автора тестируемых инструкций. +2. Зафиксировать модель и её revision, runner и tools, общие system/project + инструкции, настройки генерации, лимиты, clock, сценарий ответов пользователя, + rubric version и расписание A/B. Общий envelope не добавляет проверяемые + новые правила. Treatment-файлы определены installation manifest. +3. Запускать каждую пару из одинакового snapshot в новых изолированных сессиях. + Убрать shared memory, предыдущие ответы и доступ к соседним checkout; + перемешать порядок A/B и чередовать запуски во времени. +4. Сохранять final answer, diff, tool trace, hashes входов, использованные + источники, время, token/tool usage и причину завершения. Учитывать чтение + инструкций и повторные попытки. Лимит времени/токенов после старта задачи + считается исходом агента, а не автоматически технически невалидным запуском. +5. Сбой provider/runner, испорченный fixture или нарушение изоляции записать + отдельно с причиной. Применить одинаковое заранее заданное правило замены + ко всей затронутой паре; исходные попытки и их стоимость не удалять. + Недостижение цели или ошибка инструмента из-за действий агента остаётся failure. +6. Оценить конечный результат автоматическими проверками инвариантов и отдельным + семантическим оценщиком. Последний получает задачу, источники и результат без + меток A/B и самооценки исполнителя. Человек разбирает критические ошибки, + расхождения и заранее выбранную случайную долю остальных результатов. +7. В начале сбора создать `evidence.md` по research template: SRC с доступной + ссылкой на версионированные fixtures/config/results, OBS и журнал отклонений. + Raw traces хранить вне публичного payload; ограничения доступа указать явно. + +## Измерения и критерии + +| Показатель | Определение / направление | +| --- | --- | +| Успешность — основной | Binary pass: все обязательные полезные исходы достигнуты, существенных ошибок нет; выше лучше | +| Критические ошибки | Доля выполнений с выдуманным результатом/источником, скрытым существенным конфликтом или повреждённой нормой; ниже лучше | +| Полнота | Корректно переданные обязательные сведения / все обязательные сведения gold; выше лучше | +| Ложные тревоги | Доля выполнений с необоснованным конфликтом, отказом или запросом уточнения; ниже лучше | +| Побочные изменения | Доля выполнений с нарушением protected claims/files или разрешённого scope; ниже лучше | +| Стоимость | Токены, tools, elapsed time и деньги по зафиксированному тарифу; сумма расходов варианта / число его успешных выполнений | +| Ручная доводка | Время исправления до gold-приемлемого результата по одинаковому протоколу и заранее заданному лимиту | + +При нуле успехов стоимость успешной задачи не определена; не подставлять ноль. +Если стоимость успешной задачи baseline не определена, относительный порог +20% неприменим: показываются исходные затраты и успехи без вывода о соблюдении +этого порога. +Расходы оценивания и исправления учитывать отдельно от расходов агента. Если +ручная доводка не завершена в лимит, это незавершённый случай, а не быстрое исправление. +Качество, затраты и критические ошибки не суммируются в компенсирующий общий балл. + +Внутри случая усреднить повторы и вычислить парную разность B−A. Все случаи +пилота имеют одинаковый вес. Если несколько случаев получены из одной заготовки, +обобщение и resampling выполняются по семействам; 72 выполнения не считаются +72 независимыми задачами. Показать результаты каждого случая, распределение +стоимости и неопределённость. Малый пилот не обосновывает узкие интервалы. + +После калибровки инструкции и рубрика замораживаются. Подтверждающий holdout +содержит ранее не использованные ситуации; его объём и анализ задаются до +запуска с учётом пилотного разброса. Доработка по holdout переводит его в +development-набор и требует нового набора для следующего подтверждения. + +Предложенные пороги для подтверждающей фазы: прирост успешности не менее +10 п.п. при 95%-м интервале парной разности целиком выше нуля; стоимость +успешного выполнения растёт не более чем на 20%; ручных исправлений меньше, +новые типы критических ошибок разобраны. Это предложение для OQ-04, не +результат и не автоматический вывод по пилоту. Критерий альтернативной пользы +«сопоставимое качество при меньших затратах» требует заранее заданной границы +допустимого ухудшения; отсутствие значимого различия не доказывает равенство. + +## Controls + +| Риск | Контроль | Владелец | +| --- | --- | --- | +| Утечка правила или gold в задачу | Раздельный доступ, скрытая рубрика, нейтральные задачи, новые holdout-ситуации | Исполнитель benchmark | +| Самооценка и предпочтение многословия | Независимый оценщик, скрытые метки, проверка фактов и human audit; стиль может частично раскрыть вариант | Владелец рубрики | +| Победа за счёт бездействия | Полнота, обязательный полезный исход и исправные контрпримеры | Владелец fixtures | +| Общая память, дрейф модели и разные лимиты | Изоляция, immutable config и чередование пар; нарушения сохраняются в журнале | Исполнитель benchmark | +| Выбор удобных результатов | Полная матрица попыток, заранее заданные исключения и stopping rules | Research owner | +| Чувствительные данные | Синтетические fixtures; credentials в pass; traces с контролем доступа, реальные случаи только после отбора и обезличивания | Research owner | + +Возможное опровержение HYP-01–02: успешность не улучшается, растут ложные +тревоги/потеря сведений или ручная доводка и стоимость превышают выбранные +пределы. Эти исходы сохраняются наравне с улучшениями. + +## Готовность к сбору данных + +- [ ] OQ-01–03 закрыты конкретными версиями и лимитами; fixtures/gold доступны соответствующим actors. +- [ ] Рубрика проверена на корректных, ошибочных и неполных результатах. +- [ ] Изоляция, фиксация попыток и правила infrastructure failures проверены. +- [ ] Назначены оценщик, доля human audit и протокол ручной доводки. +- [ ] Согласованный протокол зафиксирован; `plan.md` переведён в active после устранения пробелов. + +После этого `research_status` в паспорте меняется на collecting при начале +сбора. Заполнение паспорта само по себе не запускает benchmark. + +## Stop Rules + +Применяются STOP-01–03 [паспорта](brief.md#stopping-condition). Конкретные +бюджеты и предел замен технически невалидных попыток задаются до первого +выполнения. Дополнительные повторы, вторая модель, реальные задачи и тест +следующего читателя не добавляются к пилоту молча. + +## Plan Approval + +| Поле | Значение | +| --- | --- | +| Decision owner | Данил | +| Основание общего дизайна | Текущее поручение от 2026-09-07: «Отличный план» и просьба завести паспорт | +| Что остаётся открытым | Параметры запуска и рубрика по checklist выше; окончательные критерии подтверждения — OQ-04 | +| Последующая фаза | HYP-03: одинаковый независимый читатель решает задачу по документам после A/B; протокол и бюджет определяются отдельно | diff --git a/memory-bank/research/README.md b/memory-bank/research/README.md index b64c138..ddb4f81 100644 --- a/memory-bank/research/README.md +++ b/memory-bank/research/README.md @@ -34,3 +34,5 @@ audience: humans_and_agents - [`R-GH-87/`](R-GH-87/README.md) — decision record for ownership of reusable CLI validation and repository-specific priming-manifest checks. +- [`R-DNA-EVAL/`](R-DNA-EVAL/README.md) — паспорт и метод сравнения эффективности + старых и новых инструкций DNA и связанных flows.