Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 12 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
20 changes: 13 additions & 7 deletions README.ru.md
Original file line number Diff line number Diff line change
Expand Up @@ -139,13 +139,19 @@ Memory Bank полезен, когда замысел проекта прихо

### ДНК и единственный источник истины

`dna/` — конституция базы знаний. Здесь определены принцип единственного источника истины,
владение документами, направление зависимостей, жизненный цикл, метаданные и правила
навигации.

Канонический документ владеет фактом. Другой документ может вывести из него требование, план или
представление, но обязан сохранить зависимость от источника. Если документы противоречат друг
другу, правила владения и направление зависимостей указывают авторитетный источник.
`dna/` задаёт правила достоверной документации проекта: владение источниками,
основания утверждений, область применимости, актуальность, метаданные публикации
и навигацию. В `flows/` находятся исполнение задач, полномочия агента и проверки
разработки.

Канонический документ владеет утверждением в объявленном контексте. Производные
требования, планы и представления сохраняют источник и его ограничения.
Публикация со статусом `active` может содержать явно непроверенное предположение;
сам статус не доказывает утверждение.

При расхождении документов сравнивают утверждения, области применимости,
владельцев и смысловые зависимости. Неоднозначное владение остаётся явным
конфликтом до разрешения; более свежая правка не получает автоматический приоритет.

### Знания о проекте

Expand Down
6 changes: 6 additions & 0 deletions docs/context-priming.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
37 changes: 21 additions & 16 deletions docs/glossary.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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

Expand All @@ -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

Expand Down Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion memory-bank/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 или использовать шаблон.
Expand Down
102 changes: 102 additions & 0 deletions memory-bank/adr/ADR-002-documentation-trust-boundary.md
Original file line number Diff line number Diff line change
@@ -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.
3 changes: 3 additions & 0 deletions memory-bank/adr/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
20 changes: 20 additions & 0 deletions memory-bank/features/FT-DNA/README.md
Original file line number Diff line number Diff line change
@@ -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.
Loading
Loading