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
4 changes: 4 additions & 0 deletions template/memory-bank/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,10 @@ audience: humans_and_agents
- [`flows/README.md`](flows/README.md)
Читать, когда нужно: создать use case, epic/feature package, провести артефакт по lifecycle gates или использовать шаблон.

- [`flows/execution-handoff.md`](flows/execution-handoff.md)
Читать, когда нужно: безопасно продолжить одну конкретную задачу по compact,
read-only и evidence-backed проекции наблюдаемого исполнения.

- [`adr/README.md`](adr/README.md)
Читать, когда нужно: найти или завести Architecture Decision Record.

Expand Down
1 change: 1 addition & 0 deletions template/memory-bank/domain/glossary.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@ canonical_for:
| Term | Meaning | Context | Do not confuse with |
| --- | --- | --- | --- |
| `domain-term` | Что термин означает в проекте | Где используется | Похожие product, UI или technical terms |
| `Execution Handoff` | Derived, read-only, evidence-backed projection наблюдаемого исполнения одной задачи; каждый item ссылается на primary source | Continuation после execution | Canonical Memory Bank owner, declared priming context или session-state owner |

## Naming Rules

Expand Down
2 changes: 1 addition & 1 deletion template/memory-bank/epics/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ audience: humans_and_agents
| Intent | `charter.md`, source refs, stakeholder channels | Зачем существует epic, что входит/не входит, какие facts уже подтверждены |
| Governance | `roadmap.md`, `decision-log.md`, `risks.md`, `subissues.md` | Как исполнять epic, какие решения приняты, какие риски и subissues управляются |
| Knowledge | `design.md`, `specs/**`, `diagrams/**`, linked `UC-*` | Нормализованные требования, bounded contexts, сценарии, контракты и audit trail |
| Execution Handoff | future `memory-bank/features/FT-<issue>/` | Конкретные code changes, тесты, rollout/backout для одного approved delivery issue |
| Feature delivery | future `memory-bank/features/FT-<issue>/` | Конкретные code changes, тесты, rollout/backout для одного approved delivery issue; при необходимости их observed execution передаётся отдельным Execution Handoff |

`README.md` обязателен с начала package и индексирует только реально существующие документы. `brief.md` обязателен при выборе Epic Intake и отсутствует только при прямом Bootstrap Epic; knowledge-файлы опциональны. Любой Markdown внутри epic package должен быть reachable из package `README.md` или owner-документа и следовать правилам frontmatter из [`../flows/epic.md`](../flows/epic.md).

Expand Down
3 changes: 3 additions & 0 deletions template/memory-bank/flows/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ derived_from:
- epic.md
- use-case.md
- feature.md
- execution-handoff.md
- feature-artifact-catalog.md
- templates/README.md
status: active
Expand All @@ -27,6 +28,8 @@ audience: humans_and_agents

- [Task Routing](routing.md) — порядок выбора flow, routing predicates, повторный routing и Human Routing.
- [Task Context Priming](priming/README.md) — общий P0/P1/P2 contract, universal DNA baseline и per-process YAML manifests.
- [Execution Handoff Contract](execution-handoff.md) — compact read-only projection
observed execution с direct primary-source references для continuation одной задачи.
- [Research & Discovery Flow](research.md) — evidence-backed lifecycle research-задач, от question framing до decision и handoff без преждевременного delivery.
- [Incident And PIR Flow](incident.md) — containment, recovery, timeline, RCA, PIR и prevention work.
- [Bug Fix Flow](bug-fix.md) — reproduction, analysis, fix, regression coverage и closure.
Expand Down
90 changes: 90 additions & 0 deletions template/memory-bank/flows/execution-handoff.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,90 @@
---
title: Execution Handoff Contract
doc_kind: process
doc_function: canonical
purpose: Определяет компактный evidence-backed, derived и read-only handoff фактически выполненной работы для безопасного продолжения конкретной задачи.
derived_from:
- ../dna/governance.md
- priming/context-priming.md
- feature.md
status: active
audience: humans_and_agents
canonical_for:
- execution_handoff_term
- execution_handoff_lifecycle
- execution_handoff_schema
- execution_handoff_provenance_rules
---

# Execution Handoff Contract

`Execution Handoff` — компактная, производная и read-only проекция наблюдаемого
исполнения одной конкретной задачи. Она помогает человеку или агенту безопасно
продолжить работу, но не становится source of truth: requirements, scope,
решения, lifecycle state и verification facts остаются у своих canonical owners
в Memory Bank, task tracker, VCS и CI.

Handoff можно создать вручную или детерминированным инструментом; LLM не
является prerequisite. Он не редактирует, не merge-ит и не назначает owner-ов
документам.

## Declared And Observed Context

[`Context Priming`](priming/context-priming.md) — это **declared context**:
P0/P1/P2 inputs, которые должны быть прочитаны перед route или stage. Execution
Handoff — это **observed context**: только actions, revisions, results и
неопределённости, подтверждённые первичным источником во время или после
исполнения. Объявленный input не доказывает, что он был прочитан или что работа
по нему была выполнена; наблюдаемый result не заменяет upstream owner.

## Lifecycle

1. Начни только от одного starting task owner или document и зафиксируй его
direct source reference.
2. Собери только факты, нужные для продолжения этого task: canonical owners,
declared inputs, observed changes, verification и следующий шаг.
3. Для каждого item сохрани direct reference на первичный carrier. Не выводи
semantic relationship, completion или status из похожего имени, соседнего
файла либо отсутствия evidence.
4. Проверь, что ссылки разрешимы, а handoff не добавляет facts, которые должны
сначала попасть к canonical owner. При расхождении обнови owner по его flow,
затем создай новую проекцию.
5. Заморозь handoff для передачи. После freeze не редактируй его: при новом
наблюдении создай новый handoff с новой source revision.

## Schema

Каждый заполненный item использует `claim` и `primary_source`; optional
`observed_at` указывает момент наблюдения. `primary_source` — direct path с
section/identifier, immutable commit URL/SHA, CI run URL, task/PR comment URL
или другой carrier, по которому получатель может проверить claim. Если такого
источника нет, item записывается как open question, а не как fact.

| Section | Required content | Primary source for every item |
| --- | --- | --- |
| Starting point | task owner или starting document, source revision и handoff scope | task URL или direct document path/section |
| Declared priming context | применимые P0/P1/P2 source sets и resolved exact inputs | process manifest, resolved manifest или task owner |
| Canonical context | canonical documents и explicit upstream dependencies, реально нужные для continuation | direct owner path/section или immutable external source |
| Decisions | применимые accepted или pending decisions; `none`, если подтверждённо нет | decision owner, ADR или task owner |
| Observed execution | выполненные actions и их result без inferred semantics | commit, command log, task/PR record или CI run |
| Changed delivery | changed files, commits и current revision; `none`, если изменений нет | immutable commit/diff or VCS record |
| Verification | verification artefacts, command/result, CI и manual evidence | test output, CI run, screenshot or other direct carrier |
| Continuation | open questions, blockers, exact next step, owner и stop condition | canonical owner, task/PR record или explicit `unknown` marker |

## Consumption Rules

- Читай handoff после declared priming для текущего route/stage, а не вместо
него. При conflict первичен canonical owner или immutable evidence по rules
[`Document Governance`](../dna/governance.md).
- Ограничь handoff одной задачей и ближайшим continuation decision; вместо
истории проекта дай direct refs на более глубокие источники.
- Потребитель сверяет starting revision, ссылки и blockers перед первым write.
Если они расходятся с current sources, handoff является stale и task возвращается
к applicable gate или Task Routing.

## Non-Goals

Execution Handoff не является universal priming report, status register,
requirements/design/plan replacement или журналом, из которого выводятся новые
семантические связи. Он не закрывает flow gate сам по себе: gate evidence
остаётся у владельца соответствующего lifecycle.
38 changes: 37 additions & 1 deletion template/memory-bank/flows/feature.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,8 @@ audience: humans_and_agents
затем добавляй source sets перед соответствующими стадиями. `design` обязателен
при `Design required: yes`; `ui_design`, `interaction_runtime_design` и
`scenario_design` обязательны при выборе соответствующего artifact; далее
выполни `plan_ready` и `execution_continuation`.
выполни `plan_ready` и `execution_continuation`. Перед созданием Execution
Handoff выполни `execution_handoff`.

Task owner добавляет exact affected implementation and test paths в
`implementation-plan.md`. Stage priming не заменяет execution grounding с
Expand Down Expand Up @@ -359,6 +360,41 @@ Plan Ready artifact-review convergence допускает не более пят

Закрой delivery issue и передай эксплуатационные или release-действия их owner-ам. Новые требования, решения и follow-up работу обнови у canonical owner и повторно маршрутизируй.

### Worked Execution Handoff Example

Ниже synthetic example формы, а не факт о существующей feature. Конкретная
передача заменяет все placeholder значения direct primary-source references по
[Execution Handoff Contract](execution-handoff.md).

```text
Starting point
- claim: FT-042 is at Execution → Done verification.
primary_source: memory-bank/features/FT-042/brief.md#delivery-status

Declared priming context
- claim: the execution continuation source set was resolved for FT-042.
primary_source: memory-bank/flows/priming/feature.yaml#execution_continuation

Observed execution
- claim: STEP-03 was executed at immutable revision <commit-sha>.
primary_source: <commit-url-or-command-log>#STEP-03

Verification
- claim: CHK-02 passed.
primary_source: <ci-run-url-or-test-output>#CHK-02

Continuation
- claim: release approval is still required before production action.
primary_source: memory-bank/features/FT-042/implementation-plan.md#AG-01
- next action: release owner requests AG-01 approval; stop if the approved
revision differs from <commit-sha>.
primary_source: memory-bank/features/FT-042/implementation-plan.md#AG-01
```

Здесь declared priming context показывает, что должно было быть загружено;
observed execution доказывается отдельным commit, command log или CI carrier.
Ни одна строка handoff не меняет `brief.md`, design owner или plan.

## Boundary Rules

1. `brief.md` обязан содержать секции `What` и `Verify`.
Expand Down
2 changes: 2 additions & 0 deletions template/memory-bank/flows/priming/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,8 @@ audience: humans_and_agents
# Context Priming

- [Context Priming Contract](context-priming.md) — P0/P1/P2 contract.
- [Execution Handoff Contract](../execution-handoff.md) — derived observed
execution context; не заменяет declared priming inputs или canonical owners.
- [Universal governance baseline](universal-baseline.yaml) — DNA inputs перед
созданием или обновлением любого governed-артефакта.
- [Routing manifest](routing.yaml) — P0 и Human Routing.
Expand Down
12 changes: 12 additions & 0 deletions template/memory-bank/flows/priming/context-priming.md
Original file line number Diff line number Diff line change
Expand Up @@ -109,6 +109,16 @@ Brief priming не заменяет это evidence;
[`implementation-plan.md`](../templates/feature/implementation-plan.md)
содержит отдельный exact implementation manifest для агента перед первым write.

## Declared Priming And Observed Execution

P0/P1/P2 и resolved manifests — declared context: они называют sources, которые
нужно прочитать перед decision или stage, но сами не доказывают, что действие
было выполнено. Когда конкретную задачу нужно продолжить после исполнения,
используй [Execution Handoff Contract](../execution-handoff.md) как отдельную
read-only projection observed context. Он фиксирует только evidence-backed
actions/results и direct primary sources; не становится priming report или
owner-ом facts.

## Ownership

- Этот документ владеет P0/P1/P2 model и manifest schema.
Expand All @@ -119,3 +129,5 @@ Brief priming не заменяет это evidence;
какой manifest и source set выполнить.
- Task owner владеет resolved task inputs и evidence. Не создавай отдельный
universal priming report или central source matrix.
- Execution Handoff владеет только формой derived observed-context projection;
его facts остаются у указанных primary sources.
2 changes: 2 additions & 0 deletions template/memory-bank/flows/priming/feature.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -38,3 +38,5 @@ stages:
execution_continuation:
- memory-bank/features/<FT-ID>/*.md
- memory-bank/engineering/git-workflow.md
execution_handoff:
- memory-bank/flows/execution-handoff.md
Loading