From 112c2e2183e4e092bdb3cfdf3bb8d13813417028 Mon Sep 17 00:00:00 2001 From: Danil Pismenny Date: Wed, 5 Aug 2026 07:26:35 +0300 Subject: [PATCH] docs: define execution handoff --- template/memory-bank/README.md | 4 + template/memory-bank/domain/glossary.md | 1 + template/memory-bank/epics/README.md | 2 +- template/memory-bank/flows/README.md | 3 + .../memory-bank/flows/execution-handoff.md | 90 +++++++++++++++++++ template/memory-bank/flows/feature.md | 38 +++++++- template/memory-bank/flows/priming/README.md | 2 + .../flows/priming/context-priming.md | 12 +++ .../memory-bank/flows/priming/feature.yaml | 2 + 9 files changed, 152 insertions(+), 2 deletions(-) create mode 100644 template/memory-bank/flows/execution-handoff.md diff --git a/template/memory-bank/README.md b/template/memory-bank/README.md index 008eb77..2dd37b3 100644 --- a/template/memory-bank/README.md +++ b/template/memory-bank/README.md @@ -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. diff --git a/template/memory-bank/domain/glossary.md b/template/memory-bank/domain/glossary.md index b1e85d8..46b258f 100644 --- a/template/memory-bank/domain/glossary.md +++ b/template/memory-bank/domain/glossary.md @@ -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 diff --git a/template/memory-bank/epics/README.md b/template/memory-bank/epics/README.md index 3e70af8..f579517 100644 --- a/template/memory-bank/epics/README.md +++ b/template/memory-bank/epics/README.md @@ -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-/` | Конкретные code changes, тесты, rollout/backout для одного approved delivery issue | +| Feature delivery | future `memory-bank/features/FT-/` | Конкретные 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). diff --git a/template/memory-bank/flows/README.md b/template/memory-bank/flows/README.md index 1b41539..0dd824d 100644 --- a/template/memory-bank/flows/README.md +++ b/template/memory-bank/flows/README.md @@ -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 @@ -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. diff --git a/template/memory-bank/flows/execution-handoff.md b/template/memory-bank/flows/execution-handoff.md new file mode 100644 index 0000000..07af078 --- /dev/null +++ b/template/memory-bank/flows/execution-handoff.md @@ -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. diff --git a/template/memory-bank/flows/feature.md b/template/memory-bank/flows/feature.md index 5b82605..d79ee93 100644 --- a/template/memory-bank/flows/feature.md +++ b/template/memory-bank/flows/feature.md @@ -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 с @@ -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 . + primary_source: #STEP-03 + +Verification +- claim: CHK-02 passed. + primary_source: #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 . + 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`. diff --git a/template/memory-bank/flows/priming/README.md b/template/memory-bank/flows/priming/README.md index 5433232..2e6a9f4 100644 --- a/template/memory-bank/flows/priming/README.md +++ b/template/memory-bank/flows/priming/README.md @@ -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. diff --git a/template/memory-bank/flows/priming/context-priming.md b/template/memory-bank/flows/priming/context-priming.md index 5afb133..3ac9c5a 100644 --- a/template/memory-bank/flows/priming/context-priming.md +++ b/template/memory-bank/flows/priming/context-priming.md @@ -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. @@ -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. diff --git a/template/memory-bank/flows/priming/feature.yaml b/template/memory-bank/flows/priming/feature.yaml index c51d445..62f39e0 100644 --- a/template/memory-bank/flows/priming/feature.yaml +++ b/template/memory-bank/flows/priming/feature.yaml @@ -38,3 +38,5 @@ stages: execution_continuation: - memory-bank/features//*.md - memory-bank/engineering/git-workflow.md + execution_handoff: + - memory-bank/flows/execution-handoff.md