Skip to content
Merged
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
1 change: 1 addition & 0 deletions README.ru.md
Original file line number Diff line number Diff line change
Expand Up @@ -106,6 +106,7 @@ service setup-команды проекта; он намеренно не пер
### Методические источники

- [MECE principle](https://en.wikipedia.org/wiki/MECE_principle) — определение принципа Mutually Exclusive, Collectively Exhaustive: непересекающиеся категории, которые вместе покрывают заявленную область;
- Dan North, [*Introducing BDD*](https://dannorth.net/blog/introducing-bdd/) — первичный источник Behaviour-Driven Development: уточнение требований через business value, concrete examples и executable acceptance scenarios в форме `Given / When / Then`;
- Philippe Kruchten, [*Architectural Blueprints — The “4+1” View Model of Software Architecture*](https://arxiv.org/abs/2006.04975) — первичный источник stakeholder-oriented проверки Logical, Process, Development и Physical views через driving scenarios; [краткий обзор](https://en.wikipedia.org/wiki/4%2B1_architectural_view_model);
- Nenad Medvidovic, Richard N. Taylor, [*A Classification and Comparison Framework for Software Architecture Description Languages*](https://ics.uci.edu/~taylor/documents/2000-ADLs-TSE.pdf) — источник архитектурной модели components, connectors и configurations.

Expand Down
6 changes: 2 additions & 4 deletions memory-bank/.lock
Original file line number Diff line number Diff line change
Expand Up @@ -169,11 +169,9 @@
"payload_mode": "100644"
},
"memory-bank/features/README.md": {
"ownership": "managed",
"ownership": "adapted",
"base_digest": "sha256:b566792f535872b80432e6c5290a618aac32e3970c63d5f50fc8d8f863a3d312",
"payload_digest": "sha256:b566792f535872b80432e6c5290a618aac32e3970c63d5f50fc8d8f863a3d312",
"base_mode": "100644",
"payload_mode": "100644"
"base_mode": "100644"
},
"memory-bank/flows/README.md": {
"ownership": "managed",
Expand Down
22 changes: 22 additions & 0 deletions memory-bank/features/FT-113/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
---
title: "FT-113: Integrate BDD behavior specification practice"
doc_kind: feature
doc_function: index
purpose: "Навигация по delivery-пакету интеграции BDD-практики в Memory Bank."
derived_from:
- ../../flows/feature.md
- brief.md
status: active
audience: humans_and_agents
---

# FT-113: Integrate BDD behavior specification practice

## Аннотированный индекс

- [`brief.md`](brief.md) — problem, scope и canonical verify contract.
- [`implementation-plan.md`](implementation-plan.md) — active execution и
verification plan; resulting active revision ожидает final clean re-review.

Изменения generic template находятся в `template/memory-bank/`; этот package
остаётся source-repository delivery trace и не попадает в downstream payload.
144 changes: 144 additions & 0 deletions memory-bank/features/FT-113/brief.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,144 @@
---
title: "FT-113: Integrate BDD behavior specification practice"
doc_kind: feature
doc_function: canonical
purpose: "Фиксирует delivery-единицу по описанию BDD как практики внутри существующих Feature и Use Case Flow."
derived_from:
- ../../flows/feature.md
status: active
delivery_status: planned
audience: humans_and_agents
source_issue: https://github.com/dapi/memory-bank/issues/113
must_not_define:
- implementation_sequence
- solution_space
---

# FT-113: Integrate BDD behavior specification practice

## What

### Problem

Memory Bank различает `UC-*`, `REQ-*`, `SC/NEG-*`, `CHK-*`, `EVID-*` и
feature-local `FUC-*`, но не описывает их связь в процессе discovery → concrete
examples → проверка поведения. Без общего контракта проекты могут дублировать
требования в Gherkin, сводить BDD к E2E и создавать параллельных владельцев
сценариев.

### Outcome

Memory Bank однозначно описывает переход от обсуждения поведения к concrete
examples и проверке, границу между project-level use cases и feature acceptance,
а также ownership и traceability существующих artifacts.

## Scope

- `REQ-01` Описать переход от обсуждения поведения к concrete examples и затем
к проверке поведения.
- `REQ-02` Определить, где фиксировать найденное поведение, когда создавать
project-level `UC-*`, когда достаточно feature-level `SC-*` / `NEG-*`, где
живут `Given / When / Then` examples и кто владеет acceptance semantics.
- `REQ-03` Связать examples с существующими requirements, acceptance checks и
evidence и объяснить BDD как практику анализа и проверки поведения, а не
только E2E-инструмент, без противоречивых владельцев artifacts.

## Non-Scope

- `NS-01` Новый BDD route, каталог, identifier family или второй canonical
owner. Это derived governance constraint из существующего Task Routing и SSoT,
а не дословное требование issue.
- `NS-02` Обязательные Gherkin, Cucumber, browser automation или E2E: первичные
источники [Dan North](https://dannorth.net/blog/introducing-bdd/) и
[Cucumber BDD Guide](https://cucumber.io/docs/bdd/) описывают BDD шире
конкретного инструмента или test level.
- `NS-03` Bulk migration downstream packages: issue её не запрашивает.

## Design Requirement Decision

| Decision | Reason | Downstream owner |
| --- | --- | --- |
| `Design required: no` | Existing governance уже назначает owners и routes; feature документирует и связывает этот contract, не выбирая новую architecture, owner hierarchy или runtime/interface solution. | none |

## Validation Profile Decision

| Profile | Triggers / rationale | Downgrade approval |
| --- | --- | --- |
| `documentation` | Generic template documentation, indexes and validation tooling only. | none |

## Behavior Specification Contract

Следующие правила являются derived governance resolution требований issue, а не
их дословной цитатой. Они выводятся из существующих SSoT owners, Task Routing и
Feature/Use Case lifecycle.

BDD применяется как практика уточнения поведения внутри выбранного delivery
flow, а не как отдельный route, каталог или обязательный E2E-инструмент.

- Устойчивый повторяющийся project-level сценарий с trigger, preconditions,
flow и postconditions принадлежит `UC-*`.
- Правило, относящееся только к этой delivery-unit, принадлежит `REQ-*` в
`brief.md`.
- Concrete examples хранятся как `SC-*` или `NEG-*` в `brief.md`. При
существенной неоднозначности example использует `Given / When / Then`:
начальное состояние, одно значимое событие и наблюдаемый результат.
- `CHK-*` фиксирует способ проверки и expected verdict; `EVID-*` фиксирует
наблюдаемый результат проверки. Цепочка не передаёт ownership test code или
feature-local companion.
- Существующие `FUC-*` и другие feature-local companions могут только показывать
derived projection и mapping для review; это integration boundary, а не новая
customer capability.
- Gherkin, Cucumber, browser automation и E2E не являются обязательными;
выбирается самый надёжный test surface, доказывающий observable behavior.

## Verify

| Requirement | Acceptance | Checks | Evidence |
| --- | --- | --- | --- |
| `REQ-01` | `SC-01` Practice defines the transition from behavior discussion through concrete examples to verification. | `CHK-01`, `CHK-02` | `EVID-01`, `EVID-02` |
| `REQ-02` | `SC-02` A discovered behavior is routed to `UC-*`, `REQ-*`, `SC-*` or `NEG-*` by an explicit ownership criterion, and structured examples have a defined home. | `CHK-01` | `EVID-01` |
| `REQ-03` | `SC-03` Requirements and examples trace through checks to evidence without making BDD E2E-only or creating another owner. | `CHK-01`, `CHK-02` | `EVID-01`, `EVID-02` |

### Concrete Examples

#### SC-01: Переход от обсуждения к проверке

- Rule refs: `REQ-01`
- Given: команда обсуждает требуемое наблюдаемое поведение
- When: она уточняет его через concrete examples и готовит проверку
- Then: Memory Bank задаёт непрерывный путь Discussion/Discovery → Formulation
→ Verification/Automation
- Checks: `CHK-01`, `CHK-02`

#### SC-02: Маршрутизация найденного поведения

- Rule refs: `REQ-02`
- Given: discovery выявил устойчивый project flow, feature-specific rule и
positive или negative example
- When: команда выбирает canonical owner
- Then: устойчивый reusable flow направляется в `UC-*`, feature-specific rule —
в `REQ-*`, а examples — в `SC-*` / `NEG-*`; optional `FUC-*` остаётся derived
- Checks: `CHK-01`

#### SC-03: Проверяемая цепочка без E2E-only ограничения

- Rule refs: `REQ-03`
- Given: `SC-*` или `NEG-*` содержит context, event и observable outcome
- When: команда выбирает техническую или approved manual-only проверку
- Then: `CHK-*` связывает example с подходящим test surface, `EVID-*` содержит
concrete carrier результата, а Gherkin, Cucumber и E2E не обязательны
- Checks: `CHK-01`, `CHK-02`

### Checks

| Check ID | How to check | Expected result |
| --- | --- | --- |
| `CHK-01` | Независимый requirements/artifact review issue #113, feature package и изменённых governance owners. | Review подтверждает полноту customer requirements, отсутствие второго owner и непрерывную traceability; все critical/important findings закрыты. |
| `CHK-02` | `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 doctor --profile template`; `git diff --check`. | Validators, lint, doctor и whitespace check проходят на одной immutable candidate revision. |

### Evidence

- `EVID-01` Pending: внешний clean artifact-review record с reviewer identity,
immutable candidate revision, findings/dispositions и итоговым verdict.
- `EVID-02` Pending: concrete local/CI carriers для всех команд `CHK-02`,
привязанные к той же candidate revision.
98 changes: 98 additions & 0 deletions memory-bank/features/FT-113/implementation-plan.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,98 @@
---
title: "FT-113: Implementation Plan"
doc_kind: feature
doc_function: derived
purpose: "Active execution и verification plan для FT-113."
derived_from:
- brief.md
- ../../flows/feature.md
status: active
audience: humans_and_agents
---

# FT-113: Implementation Plan

## Цель текущего плана

Добавить canonical BDD practice в generic template, связать её с существующими
flow, policy и indexes, сохранив ownership существующих artifacts.

## Lifecycle Note

Candidate implementation уже существует в commit `110fbc7ec0db62cfdad67749db5a7ed20696d3fa`.
Draft plan прошёл clean artifact review; resulting active revision должна быть
заморожена и получить final clean re-review до закрытия Plan Ready. Наличие
candidate implementation не переводит lifecycle в Execution или Done задним
числом.

## Grounding Evidence

- Grounded repository revision: `110fbc7ec0db62cfdad67749db5a7ed20696d3fa`

| Grounding ID | Inspected path / command | Observed current-state fact | Plan impact |
| --- | --- | --- | --- |
| `GRND-01` | `template/memory-bank/flows/feature.md`, `template/memory-bank/flows/use-case.md` | Feature acceptance и project-level scenarios имеют разные owners; `SC/NEG-*` остаются в feature brief. | `STEP-02` не создаёт новый route или owner. |
| `GRND-02` | `template/memory-bank/engineering/testing-policy.md`, `template/memory-bank/flows/behavior-specification.md` | Проверка поведения должна быть связана через `CHK-*` и `EVID-*`; Gherkin/Cucumber/E2E не обязательны. | `STEP-02` фиксирует test-surface-neutral automation handoff. |
| `GRND-03` | `memory-bank/features/FT-113/brief.md`, `memory-bank/features/README.md` | Feature package пока не входит в grounded revision; его candidate revision и review evidence должны быть зафиксированы отдельно. | `STEP-03` закрывает package traceability, review и lifecycle evidence до execution/closure. |

## Grounding / Support References

| Document | Role in this plan | Facts reused |
| --- | --- | --- |
| `brief.md` | canonical problem, scope and verify owner | `REQ-*`, `NS-*`, `SC-*`, `CHK-*`, `EVID-*` |
| `../../../template/memory-bank/flows/behavior-specification.md` | canonical BDD practice | ownership, Given/When/Then and automation handoff |
| `../../../template/memory-bank/flows/use-case.md` | canonical `UC-*` lifecycle | `UC-*` versus `SC/NEG-*` boundary |
| `../../../template/memory-bank/engineering/testing-policy.md` | canonical testing policy | test ownership and manual-only boundary |

## Test Strategy

| Test surface | Canonical refs | Planned verification | Required local suites / commands | Required CI | Manual-only gap |
| --- | --- | --- | --- | --- | --- |
| Requirements, ownership and traceability | `REQ-01`, `REQ-02`, `REQ-03`, `CHK-01` | Independent artifact review of frozen feature and affected governance revisions | Review issue #113 → `REQ/SC/CHK/EVID`, owner boundaries and scope; record reviewer, candidate SHA, findings/dispositions and verdict | none | Required artifact-review procedure; not a substitute for automated validation |
| Template documentation, manifests and links | `REQ-01`, `REQ-03`, `CHK-02` | Priming validators, lint, doctor and whitespace check | `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 doctor --profile template`; `git diff --check` | `validate-template` | none |

## Open Questions / Ambiguities

`none` — research resolved the issue questions through existing routing, SSoT
and Use Case selection rules. Derived resolutions are explicitly labelled in
`brief.md`; новые customer requirements из них не выводятся.

## Preconditions

| Precondition ID | Canonical ref | Required state | Used by steps | Blocks start |
| --- | --- | --- | --- | --- |
| `PRE-01` | `REQ-01`, `REQ-02`, `REQ-03` | Issue #113 and the feature brief define the documentation scope. | `STEP-01`, `STEP-02`, `STEP-03` | yes |

## Design Realization Mapping

`not applicable`: `brief.md` records `Design required: no`.

## Workstreams

| Workstream | Implements | Result | Dependencies |
| --- | --- | --- | --- |
| `WS-1` | `REQ-01`, `REQ-02` | Canonical BDD practice connected to existing Feature/Use Case owners. | `PRE-01` |
| `WS-2` | `REQ-03` | Examples connect to checks/evidence without E2E-only or duplicate ownership. | `WS-1` |
| `WS-3` | `REQ-01`, `REQ-02`, `REQ-03` | Candidate artifacts pass independent review and produce revision-bound evidence. | `WS-1`, `WS-2` |

## Порядок работ

| Step ID | Implements | Goal | Touchpoints | Verifies | Evidence IDs | Check command / procedure |
| --- | --- | --- | --- | --- | --- | --- |
| `STEP-01` | `REQ-01` | Publish the canonical discussion/discovery → formulation → verification practice. | `template/memory-bank/flows/behavior-specification.md`, applicable indexes | `CHK-01`, `CHK-02` | `EVID-01`, `EVID-02` | Inspect practice and run documentation checks |
| `STEP-02` | `REQ-02`, `REQ-03` | Publish ownership and `UC/REQ → SC/NEG → CHK → check → EVID` traceability in the minimum required owners/templates. | Feature/Use Case flows, testing policy, brief/use-case/plan templates; feature-local companion only as existing derived boundary | `CHK-01`, `CHK-02` | `EVID-01`, `EVID-02` | Inspect stable-ID mappings, concrete examples and owner boundaries |
| `STEP-03` | `REQ-01`, `REQ-02`, `REQ-03` | Freeze a candidate revision containing the feature package, complete independent artifact review and attach concrete verification carriers. | `memory-bank/features/FT-113/`, external review record, CI/local results | `CHK-01`, `CHK-02` | `EVID-01`, `EVID-02` | Review the frozen revision; run every command in `CHK-02` |

## Checkpoints

| Checkpoint ID | Refs | Condition | Evidence IDs |
| --- | --- | --- | --- |
| `CP-01` | `STEP-01`, `STEP-02`, `CHK-01`, `CHK-02` | Candidate practice, ownership boundaries and traceability are internally consistent and validation is green. | `EVID-01`, `EVID-02` |
| `CP-02` | `STEP-03`, `CHK-01`, `CHK-02` | Clean review and all concrete carriers refer to the same frozen candidate revision. | `EVID-01`, `EVID-02` |

## Evidence

- `EVID-01` pending: external clean artifact-review record with reviewer,
immutable candidate revision, findings/dispositions and verdict.
- `EVID-02` pending: local and CI outputs for every `CHK-02` command, all bound
to the same candidate revision.
5 changes: 5 additions & 0 deletions memory-bank/features/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,3 +31,8 @@ audience: humans_and_agents
- Базовый формат: `FT-XXX/`
- Вместо `XXX` используй идентификатор, принятый в проекте: issue id, ticket id или другой стабильный ключ
- Один package = одна delivery-единица

## Instantiated Packages

- [`FT-113/`](FT-113/README.md) — интеграция BDD behavior specification practice
с существующими Feature/Use Case owners и verification traceability.
2 changes: 1 addition & 1 deletion template/memory-bank/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@ audience: humans_and_agents
Читать, когда нужно: проверить SSoT rules, frontmatter contract и governance-правила документации.

- [`flows/README.md`](flows/README.md)
Читать, когда нужно: создать use case, epic/feature package, провести артефакт по lifecycle gates или использовать шаблон.
Читать, когда нужно: создать use case, epic/feature package, применить BDD-практику, провести артефакт по lifecycle gates или использовать шаблон.

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