From 0c2036c83976dc7aeafcd5a68e50c14714f2d387 Mon Sep 17 00:00:00 2001 From: Danil Pismenny Date: Wed, 5 Aug 2026 07:42:37 +0300 Subject: [PATCH 1/5] docs: systematize feature requirements --- .../memory-bank/engineering/testing-policy.md | 2 + .../engineering/validation-profiles.md | 2 +- .../flows/feature-artifact-catalog.md | 5 +- template/memory-bank/flows/feature.md | 64 ++++++++++++++++--- .../flows/templates/feature/brief.md | 33 ++++++++++ .../flows/templates/feature/design.md | 8 +++ .../templates/feature/implementation-plan.md | 9 +++ 7 files changed, 111 insertions(+), 12 deletions(-) diff --git a/template/memory-bank/engineering/testing-policy.md b/template/memory-bank/engineering/testing-policy.md index dde3907..98bff27 100644 --- a/template/memory-bank/engineering/testing-policy.md +++ b/template/memory-bank/engineering/testing-policy.md @@ -68,6 +68,8 @@ Canonical lifecycle gates живут в [../flows/feature.md](../flows/feature.m ## Что Считается Sufficient Coverage +For each applicable `REQ-*`, preserve the `brief.md` verification method and evidence contract. Quality requirements include an observable threshold and a repeatable measurement/check. The plan maps each changed implementation, test, and config path plus symbol/section back to a `REQ-*` or explicit supporting rationale; review checks that mapping in both directions. + - Покрыт основной changed behavior и ближайший regression path. - Покрыты новые или измененные contracts, события, schema или integration boundaries. - Покрыты критичные failure modes из `FM-*` в required `design.md`, bug history или acceptance risks. diff --git a/template/memory-bank/engineering/validation-profiles.md b/template/memory-bank/engineering/validation-profiles.md index 8e6b32f..3ca5122 100644 --- a/template/memory-bank/engineering/validation-profiles.md +++ b/template/memory-bank/engineering/validation-profiles.md @@ -84,7 +84,7 @@ Profile decision записывается ровно один раз; downstream | Flow | Canonical owner | Правило | | --- | --- | --- | | Small Change | issue/task routing record; draft PR только если tracker нельзя обновить | Record содержит profile, triggers/rationale и approval ref при downgrade. | -| Feature | `memory-bank/features/FT-XXX/brief.md` | `implementation-plan.md` реализует contract через suites/checkpoints, но не дублирует решение. | +| Feature | `memory-bank/features/FT-XXX/brief.md`; for the source-template exception in Feature Flow, the routed issue/task record | `implementation-plan.md` реализует contract через suites/checkpoints, но не дублирует решение. The exception carrier records the same minimum decision fields without modifying a managed downstream installation. | | Bug Fix | bug report или связанная delivery task; draft PR только как fallback | Reproduction, regression plan и evidence исполняют выбранный profile. | | Refactoring | исходная task; draft PR только как fallback | Profile учитывает blast radius и critical behavior, которое нужно сохранить. | | Incident / PIR | Не назначается containment/PIR record | Permanent remediation и prevention items получают profile после отдельного Task Routing. Incident safety gates продолжают действовать независимо. | diff --git a/template/memory-bank/flows/feature-artifact-catalog.md b/template/memory-bank/flows/feature-artifact-catalog.md index 40c42c9..593cfc2 100644 --- a/template/memory-bank/flows/feature-artifact-catalog.md +++ b/template/memory-bank/flows/feature-artifact-catalog.md @@ -35,7 +35,7 @@ audience: humans_and_agents | Project-level `UC-*` | Какой устойчивый пользовательский / операторский сценарий поддерживает система? | Scenario повторяется во времени или используется несколькими features | `memory-bank/use-cases/UC-XXX.md` | Canonical reusable scenario | [Use Case](templates/use-case/UC-XXX.md) | | Epic package | Как координируются roadmap, risks и несколько delivery units? | Работа крупнее одной vertical feature | `memory-bank/epics/EP-XXX/` | Initiative coordination, не feature execution | [Epic](templates/epic/README.md) | | `README.md` | Какие artifacts реально входят в feature package и в каком порядке их читать? | Любой feature package | `features/FT-XXX/README.md` | Routing only | [Feature README](templates/feature/README.md) | -| `brief.md` | Какую проблему решаем, что входит в scope и как принимаем результат? | Любой feature package | `features/FT-XXX/brief.md` | Canonical problem, requirements, acceptance and evidence contract | [Brief](templates/feature/brief.md) | +| `brief.md` | Какую проблему решаем, какие requirement classes применимы, что входит в scope и как принимаем результат? | Любой feature package | `features/FT-XXX/brief.md` | Canonical problem, classified requirements, acceptance, evidence and traceability contract | [Brief](templates/feature/brief.md) | | Feature-local use cases | Какие happy, edge и error journeys удобнее review отдельно? | Много scenarios/roles или нужен `FUC -> REQ -> CHK` mapping | `use-cases/README.md` | Derived scenario projection; canonical acceptance остается в `brief.md` | [Feature Use Cases](templates/feature/support/use-cases.md) | | Runtime surface inventory | Где behavior существует сейчас и какой context доступен? | Несколько entrypoints, mappings, fallbacks или context variants | `runtime-surfaces.md` | Current-state reference | [Runtime Surfaces](templates/feature/support/runtime-surfaces.md) | | UI flow / mockups | Что видит пользователь и какие interface states проходит? | Меняется UI, navigation, editor/preview или interaction model | `ui-reference/README.md`, `ui-reference/mockups/*`; ссылка на `engineering/ui-design-guide/README.md` или нужный surface document | Interface reference; requirements и selected solution остаются у canonical owners; shared UI catalog не копируется в feature | [UI Reference](templates/feature/support/ui-reference.md) | @@ -72,7 +72,7 @@ audience: humans_and_agents | Error taxonomy | Какие errors/states существуют и как consumer их интерпретирует? | API/integration или много failure outcomes | Table in contract or `design.md` | `CTR-*` wire semantics and `FM-*` solution behavior | Interaction Contract pattern | | Failure-mode analysis | Что может сломаться и как решение ограничивает impact? | Distributed, financial, security-critical или degradation-sensitive flow | `FM-*` in `design.md`; table when richer analysis needed | Canonical solution failure semantics | Design section | | Idempotency / concurrency model | Как обрабатываются duplicates, races, locks и ordering? | Callbacks, jobs, financial operations или parallel writers | Contract/design tables and sequence branches | `CTR-*`, `INV-*`, `FM-*`, `SD-*` | Interaction/Sequence patterns | -| Quality attributes / NFR | Какие latency, capacity, availability, consistency или recovery properties нужны? | Эти properties меняют класс допустимых решений | Constraints in `brief.md`; solution response in `design.md` | Requirement vs solution ownership сохраняется раздельно | pattern only | +| Quality attributes / NFR | Какие measurable latency, capacity, availability, consistency или recovery properties нужны? | Applicability decision identifies a quality trigger or material risk | `REQ-*` class `performance` or `quality attribute` in `brief.md`; solution response in `design.md` | `MET-*` and `CON-*` do not replace a requirement | Brief/Design pattern | | Security / threat analysis | Какие trust boundaries, threats и controls существуют? | Auth, permissions, secrets, personal/financial data или external integration | Compact section/table in `design.md`; при росте `security-analysis.md` | Feature controls; reusable security policy требует ADR/project owner | pattern only | | Migration design | Как перейти из current state в target state без потери compatibility? | Data/schema/config migration, dual read/write или staged cutover | `migration-design.md` или compact `RB-*` section | Delegated migration facts indexed from `design.md` | pattern only | | Compatibility matrix | Какие producer/consumer/schema versions совместимы? | Rolling deploy или independently released components | Table in contract/migration design | Delegated compatibility contract | Interaction/Migration pattern | @@ -85,6 +85,7 @@ audience: humans_and_agents | Artifact | Question answered | Trigger | Default form / suggested path | Ownership | Template | | --- | --- | --- | --- | --- | --- | | `implementation-plan.md` | В каком порядке реализовать accepted problem/solution contract? | Feature действительно переходит к execution | `features/FT-XXX/implementation-plan.md` | Workstreams, steps, commands, checkpoints and stop conditions | [Implementation Plan](templates/feature/implementation-plan.md) | +| Traceability matrix | Как requirement reaches exact code/config target, test, evidence and CI review — and back? | Every feature; expand for multiple requirements/surfaces | `brief.md` + execution mapping in plan | Brief owns requirement chain; plan owns exact realization and reverse coverage | Brief/Plan sections | | Test matrix / strategy | Какие requirements, contracts и failures чем проверяются? | Change surface требует нескольких suites/types или manual gap | Canonical checks in `brief.md`; execution strategy in plan | Acceptance remains in `brief.md`; execution coverage in plan | Brief/Plan sections | | Evidence artifact | Чем доказан конкретный check? | Evidence удобнее хранить отдельно от CI link/path/screenshot | Linkable carrier, optionally `evidence.md` | Results only; не меняет expected behavior | pattern only | | Review report | Какие findings найдены и как закрыты? | Formal review/reconciliation materially useful | `-review-report.md` or external review link | Findings/status only; canonical owners update first | pattern only | diff --git a/template/memory-bank/flows/feature.md b/template/memory-bank/flows/feature.md index 5b82605..2bba038 100644 --- a/template/memory-bank/flows/feature.md +++ b/template/memory-bank/flows/feature.md @@ -25,6 +25,8 @@ canonical_for: - feature_connector_description_rules - feature_design_verification_rules - feature_identifier_taxonomy + - feature_requirement_taxonomy + - feature_requirement_traceability_rules - solution_identifier_taxonomy - feature_plan_identifier_taxonomy - feature_traceability_rules @@ -68,12 +70,13 @@ immutable revision и `GRND-*` evidence. 10. Смысл стабильных идентификаторов (`REQ-*`, `SOL-*`, `SD-*`, `STEP-*` и т.д.) задается в секции «Stable Identifiers» ниже. 11. Acceptance scenarios (`SC-*`) покрывают delivery-unit end-to-end: для пользовательского slice — от входного события до наблюдаемого результата через все затронутые слои; для infrastructure/engineering/operations change — от system, operator или pipeline trigger до observable operational outcome. Тестирование отдельного слоя в изоляции допустимо как implementation detail плана, но не заменяет end-to-end acceptance. 12. **Связь с task tracker.** При создании feature package агент обязан добавить в исходную задачу или ticket ссылку на `brief.md`, а после появления downstream-документов — ссылки на существующие `design.md` и `implementation-plan.md`. -13. До Bootstrap / Brief агент обязан прочитать весь текущий `memory-bank/prd/*.md` corpus. Это обязательный context baseline независимо от того, зависит ли feature от конкретного PRD; PRD не заменяет сам feature package. -14. Если фича создает новый устойчивый сценарий проекта или materially changes существующий, соответствующий `UC-*` в `memory-bank/use-cases/` должен быть создан или обновлен до closure. -15. Optional feature-support docs (`runtime-surfaces.md`, `diagrams/-sequence.md`, `ui-reference/README.md`, `use-cases/README.md`) допустимы для сложных фич как grounding / review / traceability aids. Они не становятся canonical owner problem space, solution space, acceptance inventory или execution sequencing. -16. Полное чтение PRD corpus не создаёт semantic dependency от каждого PRD. `brief.md: derived_from` импортирует только фактические upstream-owner references и не копирует весь upstream scope. -17. Если работа крупнее одной delivery-feature и требует общего roadmap, cross-feature risk register или нескольких delivery units, не расширяй feature package: повтори [`Task Routing`](routing.md), выбери [`Epic Flow`](epic.md) и после epic handoff веди каждую утвержденную delivery-единицу как отдельный feature package. -18. Validation profile выбирается в `brief.md` по [`validation-profiles.md`](../engineering/validation-profiles.md). `design.md` может уточнить risk facts, а `implementation-plan.md` разворачивает minimum contract в команды, suites и checkpoints, но ни один из них не дублирует profile decision. +13. **Source-template exception.** When this repository is itself changing only its generic `template/` payload and its root `memory-bank/` is a managed downstream installation, do not create a project-specific feature package or modify that managed installation solely to mirror the delivery. The routed issue/task record is the brief-equivalent canonical carrier for scope, requirement classes, validation profile, acceptance, evidence, and lifecycle-gate decisions; the PR links back to it. This exception does not apply to a downstream project using the template: its feature delivery still uses `memory-bank/features/FT-XXX/`. +14. До Bootstrap / Brief агент обязан прочитать весь текущий `memory-bank/prd/*.md` corpus. Это обязательный context baseline независимо от того, зависит ли feature от конкретного PRD; PRD не заменяет сам feature package. +15. Если фича создает новый устойчивый сценарий проекта или materially changes существующий, соответствующий `UC-*` в `memory-bank/use-cases/` должен быть создан или обновлен до closure. +16. Optional feature-support docs (`runtime-surfaces.md`, `diagrams/-sequence.md`, `ui-reference/README.md`, `use-cases/README.md`) допустимы для сложных фич как grounding / review / traceability aids. Они не становятся canonical owner problem space, solution space, acceptance inventory или execution sequencing. +17. Полное чтение PRD corpus не создаёт semantic dependency от каждого PRD. `brief.md: derived_from` импортирует только фактические upstream-owner references и не копирует весь upstream scope. +18. Если работа крупнее одной delivery-feature и требует общего roadmap, cross-feature risk register или нескольких delivery units, не расширяй feature package: повтори [`Task Routing`](routing.md), выбери [`Epic Flow`](epic.md) и после epic handoff веди каждую утвержденную delivery-единицу как отдельный feature package. +19. Validation profile выбирается в `brief.md` по [`validation-profiles.md`](../engineering/validation-profiles.md). `design.md` может уточнить risk facts, а `implementation-plan.md` разворачивает minimum contract в команды, suites и checkpoints, но ни один из них не дублирует profile decision. The source-template exception records this decision in its issue/task carrier instead. ## Feature Package Anatomy @@ -397,6 +400,47 @@ Canonical testing policy живёт в [../engineering/testing-policy.md](../eng ## Stable Identifiers +## Requirement Taxonomy And Traceability + +`brief.md` owns the feature requirement inventory. A requirement is an externally needed outcome or condition—not a design choice, task, test, or evidence. Keep `REQ-*` as its stable identifier and record a mandatory class field; do not introduce a parallel `FR-*`/`NFR-*` namespace. `MET-*` is a goal or observed metric, `CON-*` a boundary, `EC-*` an acceptance verdict, and `CHK-*`/`EVID-*` proof. Each may link to a `REQ-*`, but none replaces it. + +For every baseline class, the brief records `applicable`, `not-applicable` with a rationale, or `covered-upstream` with its canonical reference. Functional is always applicable; the decision row itself is mandatory for all other classes. The validation profile changes verification depth, not classification. A triggered class gets a `REQ-*`; a shared fact stays in its upstream product, domain, policy, or regulatory owner. + +| Class | Level | Canonical owner / artifact | Applicability trigger | Measurement, verification, and evidence | Example / anti-example | +| --- | --- | --- | --- | --- | --- | +| stakeholder / product | stakeholder/product | shared product, PRD, or use case; otherwise `brief.md` | delivery outcome is stakeholder-specific | validate scenario outcome with its evidence | operator completes intake / internal implementation preference | +| functional | feature/system | `brief.md` `REQ-*` | always | scenario, check, and evidence | system shall accept a submission / use PostgreSQL | +| performance | feature/system/component | `brief.md` `REQ-*` | latency, throughput, capacity, or resource target | numeric threshold, repeatable measurement, report | p95 under 200 ms / “fast” | +| quality attribute | feature/system/component | `brief.md` `REQ-*` | availability, reliability, consistency, recovery, usability, maintainability, etc. | measurable criterion, method, and result carrier | recover within 15 min / add retries | +| interface | feature/system boundary | `brief.md` `REQ-*`, realized by `CTR-*` | API, CLI, event, UI, or external-system boundary | contract/interaction check and sample or CI result | webhook returns signed payload / handler class name | +| data | feature/system boundary | `brief.md` `REQ-*`, realized by `CTR-*` | schema, format, retention, integrity, or migration boundary | data/contract check and migration evidence | retain audit fields 365 days / add a column | +| security | feature/system boundary | `brief.md` `REQ-*`, controls in design | trust, auth, secret, sensitive-data, or threat trigger | analysis plus control check/evidence | only owner may export / choose OAuth library | +| safety | feature/system boundary | `brief.md` `REQ-*`, controls in design | harm, hazardous operation, or safety-critical failure trigger | hazard/failure check and result | stop device on sensor fault / standard exception wording | +| regulatory / compliance | stakeholder/product or system | policy/regulation upstream or `brief.md` | applicable obligation | procedure/check evidence | retain consent record / team style preference | +| operational | feature/system/component | `brief.md` `REQ-*`, solution/runbook in design | operator, observability, support, backup, or recovery trigger | runbook/check evidence | alert includes correlation ID / refactor package name | +| compatibility | feature/system boundary | `brief.md` `REQ-*`, mechanism in design | versioned consumer, migration, or legacy behavior trigger | compatibility matrix/contract check | v1 client remains supported / latest SDK only | +| deployment / rollout | feature/system operation | `brief.md` `REQ-*`, `RB-*` in design | staged release, flag, migration, rollback, or infra delivery trigger | rollout/backout evidence | rollback within one deploy unit / create a new module | +| constraint | any applicable level | `CON-*` in `brief.md` | imposed budget, technology, policy, date, or boundary | link testable proof where possible | must use approved region / prefer a pattern | +| verification / acceptance | feature delivery | `SC-*`, `EC-*`, `CHK-*`, `EVID-*` in `brief.md` | required for each applicable requirement; is proof, not a requirement class | method, acceptance verdict, and evidence carrier | SC proves export result / “add a test” as a requirement | + +Every applicable `REQ-*` records: class, normative measurable statement (a threshold where meaningful), source/rationale, priority, accountable owner, verification method, acceptance/check/evidence links, and realization link. Goals are `MET-*`; assumptions are `ASM-*`; constraints are `CON-*`; selected decisions, invariants, and contracts are `SD-*`/`INV-*`/`CTR-*`; acceptance is `EC-*`; evidence records a result only. + +Required chain: `upstream source → REQ-* → EC/SC → selected solution/contract or design-not-required decision → exact repository path + symbol/config section → STEP-* → CHK-* → EVID-* → review/CI result`. Each changed implementation, test, or configuration surface maps back to a `REQ-*` or an explicit supporting/necessary rationale. Paths are repository-relative and name a symbol, heading, or configuration key; a glob or module-only label is not an exact target. Lifecycle artifact review checks the chain in both directions: no orphan requirement, dangling link, duplicate owner, accepted design fact without realization target, or unexplained changed surface. + +Lint and doctor remain structural: they may validate ID format, uniqueness, resolvable links, and required template sections, but do not infer semantic applicability or a validation profile. Those judgments remain explicit brief evidence and lifecycle review, avoiding a domain-specific requirements engine. + +### Worked Traceability Examples + +| Feature kind | Requirement → realization chain | +| --- | --- | +| User-facing | `REQ-01` accessibility: “keyboard focus is visible on every dialog control” → `SC-01` keyboard journey → `CTR-01` UI contract → `web/dialog.tsx#Dialog` → `STEP-01` → `CHK-01` browser test → `EVID-01` CI result. | +| Contract / integration | `REQ-02` interface: “webhook is signed with HMAC-SHA256” → `EC-02` → `CTR-02` → `services/webhook.go#SignPayload` → `STEP-02` → `CHK-02` contract test → `EVID-02` CI result. | +| Infrastructure / operations | `REQ-03` operational: “rollback completes within one deploy unit” → `SC-03` rollback drill → `RB-01` → `infra/deploy.yaml#rollback` → `STEP-03` → `CHK-03` staging drill → `EVID-03` run record. | + +### Migration And Compatibility + +Existing feature packages remain valid: their mnemonic IDs retain their current meanings and are not silently reclassified or renamed. New active packages use the applicability matrix and fields above. An existing package adds only the applicable decision rows and trace links when it next materially changes; unknown legacy coverage is recorded as a gap or follow-up, never fabricated. + ### Feature IDs | Prefix | Meaning | Used in | @@ -464,6 +508,7 @@ Canonical testing policy живёт в [../engineering/testing-policy.md](../eng 6. Любой `design.md`, где есть принятые feature-local решения, использует `SD-*`; `ALT-*`, `TRD-*`, `CTR-*`, `INV-*`, `FM-*` и `RB-*` применяются только когда соответствующая solution-semantics действительно нужна. 7. Любой optional support doc использует только local support IDs и traceability к canonical refs; он не вводит новые canonical `REQ-*`, `SC-*`, `CHK-*` или `EVID-*`. 8. Любой `implementation-plan.md` использует как минимум `GRND-*`, `PRE-*`, `STEP-*`, `CHK-*`, `EVID-*`; при наличии ambiguity или human approval gates используются `OQ-*` и `AG-*`. +9. Any new active `brief.md` records applicability for every baseline class and the minimum fields for each applicable `REQ-*`. ### Traceability Contract @@ -471,6 +516,7 @@ Canonical testing policy живёт в [../engineering/testing-policy.md](../eng 2. Verify в `brief.md` связывает `REQ-*` с test cases через `Acceptance Scenarios`, feature-specific `NEG-*`, `Traceability matrix`, `Test matrix` и `Evidence contract`. 3. `design.md`, если есть, связывает `REQ-*` из `brief.md` с `SOL-*`, `ALT-*`, `TRD-*`, `C4-*`, `SD-*`, `CTR-*`, `INV-*`, `FM-*`, `RB-*` и accepted ADR refs. 4. `implementation-plan.md` ссылается на canonical IDs из `brief.md` и, если есть, применимые `SOL-*`, `C4-*`, `SD-*`, `CTR-*`, `INV-*`, `FM-*`, `RB-*` и accepted ADR refs в Design Realization Mapping и `Implements`; `Verifies` содержит связанные `CHK-*`, а `Evidence IDs` — подтверждающие `EVID-*`, образуя trace chain от canonical ref до evidence. -5. Если sequencing блокируется неизвестностью, план фиксирует её как `OQ-*`, а не прячет в prose. -6. Если выполнение требует человеческого подтверждения для рискованных действий, план фиксирует это через `AG-*`. -7. Если design или to-be C4 architecture model меняется после `Solution Ready`, сначала обновляется непосредственный owner из Design Pack manifest или external dependency, затем root manifest и план. +5. The plan maps every changed implementation/test/config surface to a `REQ-*` or explicit supporting rationale using exact path plus symbol/section. +6. Если sequencing блокируется неизвестностью, план фиксирует её как `OQ-*`, а не прячет в prose. +7. Если выполнение требует человеческого подтверждения для рискованных действий, план фиксирует это через `AG-*`. +8. Если design или to-be C4 architecture model меняется после `Solution Ready`, сначала обновляется непосредственный owner из Design Pack manifest или external dependency, затем root manifest и план. diff --git a/template/memory-bank/flows/templates/feature/brief.md b/template/memory-bank/flows/templates/feature/brief.md index 5d94804..da05780 100644 --- a/template/memory-bank/flows/templates/feature/brief.md +++ b/template/memory-bank/flows/templates/feature/brief.md @@ -75,6 +75,31 @@ must_not_define: ## What +### Requirement applicability and classification + +For every baseline class in [Feature Flow](../../feature.md#requirement-taxonomy-and-traceability), select `applicable`, `not-applicable` with rationale, or `covered-upstream` with reference. Do not create `FR-*`/`NFR-*`; record the class on `REQ-*`. + +| Class | Decision | Trigger / rationale / upstream reference | Requirement IDs | +| --- | --- | --- | --- | +| stakeholder / product | applicable / not-applicable / covered-upstream | | `REQ-01` / none | +| functional | applicable | | `REQ-01` | +| performance | applicable / not-applicable / covered-upstream | | | +| quality attribute | applicable / not-applicable / covered-upstream | | | +| interface | applicable / not-applicable / covered-upstream | | | +| data | applicable / not-applicable / covered-upstream | | | +| security | applicable / not-applicable / covered-upstream | | | +| safety | applicable / not-applicable / covered-upstream | | | +| regulatory / compliance | applicable / not-applicable / covered-upstream | | | +| operational | applicable / not-applicable / covered-upstream | | | +| compatibility | applicable / not-applicable / covered-upstream | | | +| deployment / rollout | applicable / not-applicable / covered-upstream | | | +| constraint | applicable / not-applicable / covered-upstream | | `CON-01` / none | +| verification / acceptance | applicable | Every applicable `REQ-*` needs proof. | `SC-01`, `EC-01`, `CHK-01`, `EVID-01` | + +| Requirement ID | Class | Normative measurable statement / threshold | Source / rationale | Priority / owner | Verification method | +| --- | --- | --- | --- | --- | --- | +| `REQ-01` | functional | The system shall … | issue / upstream reference | must / owner | test / inspection / analysis / demonstration | + ### Problem Какой симптом, ограничение или возможность делает фичу нужной. Если общий контекст уже зафиксирован upstream, здесь опиши только feature-specific вопрос delivery. @@ -179,4 +204,12 @@ Verify должен быть исполнимым. | Evidence ID | Artifact | Producer | Path contract | Reused by checks | | --- | --- | --- | --- | --- | | `EVID-01` | Лог, отчет, скриншот или sample output | verify-runner / human | `artifacts/ft-xxx/verify/chk-01/` | `CHK-01` | + +### Requirement-to-realization traceability + +`brief.md` owns the requirement chain; `design.md` owns selected solution facts and the plan supplies the exact target. A supporting change without a direct `REQ-*` needs its explicit rationale. + +| Requirement | Acceptance / check / evidence | Solution or decision | Exact realization target | Supporting rationale / review or CI result | +| --- | --- | --- | --- | --- | +| `REQ-01` | `EC-01`, `SC-01`, `CHK-01`, `EVID-01` | `SOL-01` / design-not-required decision | `path/file.ext#SymbolOrSection` | none / CI URL | ``` diff --git a/template/memory-bank/flows/templates/feature/design.md b/template/memory-bank/flows/templates/feature/design.md index 0f814a2..e14d7eb 100644 --- a/template/memory-bank/flows/templates/feature/design.md +++ b/template/memory-bank/flows/templates/feature/design.md @@ -107,6 +107,14 @@ canonical owner — `external-dependency` и не входит в состав p ## Selected Solution +## Requirement realization boundary + +`brief.md` owns requirements and acceptance. Map its applicable `REQ-*` to selected solution facts here, without adding requirements. + +| Requirement | Class | Selected solution / contract / invariant | Plan realization owner | Verification link | +| --- | --- | --- | --- | --- | +| `REQ-01` | interface | `SOL-01`, `CTR-01` | `implementation-plan.md` | `CHK-01`, `EVID-01` | + - `SOL-01` Выбранный элемент решения и почему он закрывает `REQ-*`. - `SOL-02` Второй элемент решения, если нужен. diff --git a/template/memory-bank/flows/templates/feature/implementation-plan.md b/template/memory-bank/flows/templates/feature/implementation-plan.md index 4a66028..cecc20a 100644 --- a/template/memory-bank/flows/templates/feature/implementation-plan.md +++ b/template/memory-bank/flows/templates/feature/implementation-plan.md @@ -177,6 +177,15 @@ revision. Если revision расходится или один из переч | `RB-01` | `design.md` | Migration, config or operational surface | `STEP-04` | `CHK-04` | `EVID-04` | | `../../adr/ADR-XXX-short-decision-name.md` | `../../adr/ADR-XXX-short-decision-name.md` (`accepted`) | Decision realization target | `STEP-05` | `CHK-05` | `EVID-05` | +## Exact requirement realization and reverse coverage + +Use repository-relative paths and a symbol, heading, or configuration key. A changed surface without a requirement is explicitly supporting/necessary; globs and module-only descriptions are insufficient. + +| Requirement or supporting ref | Exact implementation / test / config path + symbol/section | Change role | Steps | Checks / evidence | +| --- | --- | --- | --- | --- | +| `REQ-01` | `path/file.ext#Symbol` | direct realization | `STEP-01` | `CHK-01`, `EVID-01` | +| `SUP-01` | `path/test.ext#test_name` | supporting: why required | `STEP-02` | `CHK-02`, `EVID-02` | + ## Workstreams Разбей работу на независимые потоки с явным результатом каждого. From 9f6897ad4249920931e5b0c839238e2afaddf802 Mon Sep 17 00:00:00 2001 From: Danil Pismenny Date: Fri, 14 Aug 2026 05:18:35 +0300 Subject: [PATCH 2/5] docs: split feature requirement contract --- dependency-tree.md | 9 +- template/memory-bank/flows/README.md | 4 +- .../flows/feature-artifact-catalog.md | 1 + .../memory-bank/flows/feature-requirements.md | 154 ++++++++++++++++++ template/memory-bank/flows/feature.md | 129 +++------------ template/memory-bank/flows/priming/epic.yaml | 1 + .../memory-bank/flows/priming/feature.yaml | 1 + .../flows/templates/feature/brief.md | 6 +- .../templates/feature/implementation-plan.md | 3 +- 9 files changed, 194 insertions(+), 114 deletions(-) create mode 100644 template/memory-bank/flows/feature-requirements.md diff --git a/dependency-tree.md b/dependency-tree.md index 79f5a61..e100de6 100644 --- a/dependency-tree.md +++ b/dependency-tree.md @@ -56,6 +56,7 @@ template/memory-bank/dna/principles.md ├── template/memory-bank/flows/bug-fix.md ├── template/memory-bank/flows/epic.md ├── template/memory-bank/flows/feature.md + ├── template/memory-bank/flows/feature-requirements.md ├── template/memory-bank/flows/incident.md ├── template/memory-bank/flows/refactoring.md ├── template/memory-bank/flows/research.md @@ -92,7 +93,8 @@ template/memory-bank/dna/principles.md - Этот файл `dependency-tree.md` зависит от [`template/memory-bank/dna/governance.md`](template/memory-bank/dna/governance.md), но сознательно живет вне `template/memory-bank/`. - [`template/memory-bank/flows/routing.md`](template/memory-bank/flows/routing.md) зависит от governance и [`template/memory-bank/engineering/autonomy-boundaries.md`](template/memory-bank/engineering/autonomy-boundaries.md); branch flows используют его как upstream owner route selection. -- [`template/memory-bank/flows/feature.md`](template/memory-bank/flows/feature.md) зависит от governance, frontmatter и [`template/memory-bank/flows/routing.md`](template/memory-bank/flows/routing.md). +- [`template/memory-bank/flows/feature-requirements.md`](template/memory-bank/flows/feature-requirements.md) зависит от governance, frontmatter и [`template/memory-bank/engineering/validation-profiles.md`](template/memory-bank/engineering/validation-profiles.md); он владеет requirement taxonomy и двусторонней traceability policy. +- [`template/memory-bank/flows/feature.md`](template/memory-bank/flows/feature.md) зависит от governance, frontmatter, [`template/memory-bank/flows/routing.md`](template/memory-bank/flows/routing.md) и [`template/memory-bank/flows/feature-requirements.md`](template/memory-bank/flows/feature-requirements.md). - [`template/memory-bank/flows/research.md`](template/memory-bank/flows/research.md) зависит от governance, frontmatter и [`template/memory-bank/flows/routing.md`](template/memory-bank/flows/routing.md); он определяет lifecycle research packages и их artifact ownership. - [`template/memory-bank/flows/epic.md`](template/memory-bank/flows/epic.md) зависит от governance/frontmatter, [`template/memory-bank/flows/routing.md`](template/memory-bank/flows/routing.md) и [`template/memory-bank/flows/feature.md`](template/memory-bank/flows/feature.md); Epic Intake templates `package-README.md` и `brief.md` зависят от этого flow. - [`template/memory-bank/flows/small-change.md`](template/memory-bank/flows/small-change.md), [`template/memory-bank/flows/bug-fix.md`](template/memory-bank/flows/bug-fix.md) и [`template/memory-bank/flows/refactoring.md`](template/memory-bank/flows/refactoring.md) зависят от routing, governance и [`template/memory-bank/engineering/testing-policy.md`](template/memory-bank/engineering/testing-policy.md). @@ -101,12 +103,13 @@ template/memory-bank/dna/principles.md ### Feature-related Docs +- [`template/memory-bank/flows/feature-artifact-catalog.md`](template/memory-bank/flows/feature-artifact-catalog.md) зависит от [`template/memory-bank/flows/feature.md`](template/memory-bank/flows/feature.md) и [`template/memory-bank/flows/feature-requirements.md`](template/memory-bank/flows/feature-requirements.md). - [`template/memory-bank/engineering/testing-policy.md`](template/memory-bank/engineering/testing-policy.md) зависит от [`template/memory-bank/dna/governance.md`](template/memory-bank/dna/governance.md) и [`template/memory-bank/flows/feature.md`](template/memory-bank/flows/feature.md). - [`template/memory-bank/features/README.md`](template/memory-bank/features/README.md) зависит от [`template/memory-bank/dna/governance.md`](template/memory-bank/dna/governance.md) и [`template/memory-bank/flows/feature.md`](template/memory-bank/flows/feature.md). - [`template/memory-bank/flows/templates/feature/README.md`](template/memory-bank/flows/templates/feature/README.md) зависит от [`template/memory-bank/flows/feature.md`](template/memory-bank/flows/feature.md) и [`template/memory-bank/dna/frontmatter.md`](template/memory-bank/dna/frontmatter.md). -- [`template/memory-bank/flows/templates/feature/brief.md`](template/memory-bank/flows/templates/feature/brief.md) зависит от [`template/memory-bank/flows/feature.md`](template/memory-bank/flows/feature.md), [`template/memory-bank/dna/frontmatter.md`](template/memory-bank/dna/frontmatter.md) и [`template/memory-bank/engineering/testing-policy.md`](template/memory-bank/engineering/testing-policy.md). +- [`template/memory-bank/flows/templates/feature/brief.md`](template/memory-bank/flows/templates/feature/brief.md) зависит от [`template/memory-bank/flows/feature.md`](template/memory-bank/flows/feature.md), [`template/memory-bank/flows/feature-requirements.md`](template/memory-bank/flows/feature-requirements.md), [`template/memory-bank/dna/frontmatter.md`](template/memory-bank/dna/frontmatter.md) и [`template/memory-bank/engineering/testing-policy.md`](template/memory-bank/engineering/testing-policy.md). - [`template/memory-bank/flows/templates/feature/design.md`](template/memory-bank/flows/templates/feature/design.md) зависит от [`template/memory-bank/flows/feature.md`](template/memory-bank/flows/feature.md) и [`template/memory-bank/dna/frontmatter.md`](template/memory-bank/dna/frontmatter.md). -- [`template/memory-bank/flows/templates/feature/implementation-plan.md`](template/memory-bank/flows/templates/feature/implementation-plan.md) зависит от [`template/memory-bank/flows/feature.md`](template/memory-bank/flows/feature.md), [`template/memory-bank/dna/frontmatter.md`](template/memory-bank/dna/frontmatter.md) и [`template/memory-bank/engineering/testing-policy.md`](template/memory-bank/engineering/testing-policy.md). +- [`template/memory-bank/flows/templates/feature/implementation-plan.md`](template/memory-bank/flows/templates/feature/implementation-plan.md) зависит от [`template/memory-bank/flows/feature.md`](template/memory-bank/flows/feature.md), [`template/memory-bank/flows/feature-requirements.md`](template/memory-bank/flows/feature-requirements.md), [`template/memory-bank/dna/frontmatter.md`](template/memory-bank/dna/frontmatter.md) и [`template/memory-bank/engineering/testing-policy.md`](template/memory-bank/engineering/testing-policy.md). - Feature-support templates [`runtime-surfaces.md`](template/memory-bank/flows/templates/feature/support/runtime-surfaces.md), [`ui-reference.md`](template/memory-bank/flows/templates/feature/support/ui-reference.md) и [`use-cases.md`](template/memory-bank/flows/templates/feature/support/use-cases.md) зависят от [`template/memory-bank/flows/feature.md`](template/memory-bank/flows/feature.md) и [`template/memory-bank/dna/frontmatter.md`](template/memory-bank/dna/frontmatter.md). ### Research-related Docs diff --git a/template/memory-bank/flows/README.md b/template/memory-bank/flows/README.md index 1b41539..d9cec67 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 + - feature-requirements.md - feature-artifact-catalog.md - templates/README.md status: active @@ -34,6 +35,7 @@ audience: humans_and_agents - [Refactoring Flow](refactoring.md) — behavior-preserving restructuring, characterization coverage, checkpoints и closure gates. - [Epic Flow](epic.md) — Epic Intake/Proposal, lifecycle крупных инициатив, roadmap, decision log, risks и handoff в feature packages. - [Use Case Flow](use-case.md) — критерии, lifecycle и ownership для project-level `UC-*`, включая operational / agentic сценарии. -- [Feature Flow](feature.md) — lifecycle `brief.md -> optional design.md -> implementation-plan.md`, gates и стабильные ID (`REQ-*`, `SOL-*`, `STEP-*`). +- [Feature Flow](feature.md) — lifecycle `brief.md -> optional design.md -> implementation-plan.md` и transition gates. +- [Feature Requirements, Identifiers And Traceability](feature-requirements.md) — requirement classes, stable IDs, applicability и двусторонняя трассировка до delivered surfaces и evidence. - [Feature Artifact Catalog](feature-artifact-catalog.md) — optional problem/solution/execution artifacts, selection triggers, ownership, default forms и template availability. - [Templates Index](templates/README.md) — эталонные шаблоны governed-документов, включая PRD, use case, epic, feature и ADR. diff --git a/template/memory-bank/flows/feature-artifact-catalog.md b/template/memory-bank/flows/feature-artifact-catalog.md index 593cfc2..13791c1 100644 --- a/template/memory-bank/flows/feature-artifact-catalog.md +++ b/template/memory-bank/flows/feature-artifact-catalog.md @@ -6,6 +6,7 @@ purpose: Каталог optional артефактов для постановк derived_from: - ../dna/governance.md - feature.md + - feature-requirements.md status: active audience: humans_and_agents --- diff --git a/template/memory-bank/flows/feature-requirements.md b/template/memory-bank/flows/feature-requirements.md new file mode 100644 index 0000000..607357e --- /dev/null +++ b/template/memory-bank/flows/feature-requirements.md @@ -0,0 +1,154 @@ +--- +title: Feature Requirements, Identifiers And Traceability +doc_kind: governance +doc_function: canonical +purpose: "Определяет taxonomy feature requirements, registry стабильных идентификаторов, applicability decisions и двустороннюю traceability до verification и delivered surfaces." +derived_from: + - ../dna/governance.md + - ../dna/frontmatter.md + - ../engineering/validation-profiles.md +canonical_for: + - feature_identifier_taxonomy + - feature_requirement_taxonomy + - feature_requirement_traceability_rules + - solution_identifier_taxonomy + - feature_plan_identifier_taxonomy + - feature_traceability_rules +must_not_define: + - feature_flow_stages + - feature_solution_decisions + - feature_execution_steps +status: active +audience: humans_and_agents +--- + +# Feature Requirements, Identifiers And Traceability + +Этот документ — canonical requirements policy для [`Feature Flow`](feature.md). +Он определяет виды требований, их ownership, applicability и доказуемость. +Здесь же находится полный registry стабильных идентификаторов, связывающий +problem, solution и execution layers. Lifecycle и transition gates остаются в +`feature.md`; templates инстанцируют оба контракта. + +## Requirement Taxonomy And Traceability + +`brief.md` owns the feature requirement inventory. A requirement is an externally needed outcome or condition—not a design choice, task, test, or evidence. Keep `REQ-*` as its stable identifier and record a mandatory class field; do not introduce a parallel `FR-*`/`NFR-*` namespace. `MET-*` is a goal or observed metric, `CON-*` a boundary, `EC-*` an acceptance verdict, and `CHK-*`/`EVID-*` proof. Each may link to a `REQ-*`, but none replaces it. + +For every baseline class, the brief records `applicable`, `not-applicable` with a rationale, or `covered-upstream` with its canonical reference. Functional is always applicable; the decision row itself is mandatory for all other classes. The validation profile changes verification depth, not classification. A triggered class gets a `REQ-*`; a shared fact stays in its upstream product, domain, policy, or regulatory owner. + +| Class | Level | Canonical owner / artifact | Applicability trigger | Measurement, verification, and evidence | Example / anti-example | +| --- | --- | --- | --- | --- | --- | +| stakeholder / product | stakeholder/product | shared product, PRD, or use case; otherwise `brief.md` | delivery outcome is stakeholder-specific | validate scenario outcome with its evidence | operator completes intake / internal implementation preference | +| functional | feature/system | `brief.md` `REQ-*` | always | scenario, check, and evidence | system shall accept a submission / use PostgreSQL | +| performance | feature/system/component | `brief.md` `REQ-*` | latency, throughput, capacity, or resource target | numeric threshold, repeatable measurement, report | p95 under 200 ms / “fast” | +| quality attribute | feature/system/component | `brief.md` `REQ-*` | availability, reliability, consistency, recovery, usability, maintainability, etc. | measurable criterion, method, and result carrier | recover within 15 min / add retries | +| interface | feature/system boundary | `brief.md` `REQ-*`, realized by `CTR-*` | API, CLI, event, UI, or external-system boundary | contract/interaction check and sample or CI result | webhook returns signed payload / handler class name | +| data | feature/system boundary | `brief.md` `REQ-*`, realized by `CTR-*` | schema, format, retention, integrity, or migration boundary | data/contract check and migration evidence | retain audit fields 365 days / add a column | +| security | feature/system boundary | `brief.md` `REQ-*`, controls in design | trust, auth, secret, sensitive-data, or threat trigger | analysis plus control check/evidence | only owner may export / choose OAuth library | +| safety | feature/system boundary | `brief.md` `REQ-*`, controls in design | harm, hazardous operation, or safety-critical failure trigger | hazard/failure check and result | stop device on sensor fault / standard exception wording | +| regulatory / compliance | stakeholder/product or system | policy/regulation upstream or `brief.md` | applicable obligation | procedure/check evidence | retain consent record / team style preference | +| operational | feature/system/component | `brief.md` `REQ-*`, solution/runbook in design | operator, observability, support, backup, or recovery trigger | runbook/check evidence | alert includes correlation ID / refactor package name | +| compatibility | feature/system boundary | `brief.md` `REQ-*`, mechanism in design | versioned consumer, migration, or legacy behavior trigger | compatibility matrix/contract check | v1 client remains supported / latest SDK only | +| deployment / rollout | feature/system operation | `brief.md` `REQ-*`, `RB-*` in design | staged release, flag, migration, rollback, or infra delivery trigger | rollout/backout evidence | rollback within one deploy unit / create a new module | +| constraint | any applicable level | `CON-*` in `brief.md` | imposed budget, technology, policy, date, or boundary | link testable proof where possible | must use approved region / prefer a pattern | +| verification / acceptance | feature delivery | `SC-*`, `EC-*`, `CHK-*`, `EVID-*` in `brief.md` | required for each applicable requirement; is proof, not a requirement class | method, acceptance verdict, and evidence carrier | SC proves export result / “add a test” as a requirement | + +Every applicable `REQ-*` records: class, normative measurable statement (a threshold where meaningful), source/rationale, priority, accountable owner, verification method, acceptance/check/evidence links, and realization link. Goals are `MET-*`; assumptions are `ASM-*`; constraints are `CON-*`; selected decisions, invariants, and contracts are `SD-*`/`INV-*`/`CTR-*`; acceptance is `EC-*`; evidence records a result only. + +Required chain: `upstream source → REQ-* → EC/SC → selected solution/contract or design-not-required decision → exact repository path + symbol/config section → STEP-* → CHK-* → EVID-* → review/CI result`. Each changed implementation, test, or configuration surface maps back to a `REQ-*` or an explicit supporting/necessary rationale. Paths are repository-relative and name a symbol, heading, or configuration key; a glob or module-only label is not an exact target. Lifecycle artifact review checks the chain in both directions: no orphan requirement, dangling link, duplicate owner, accepted design fact without realization target, or unexplained changed surface. + +Lint and doctor remain structural: they may validate ID format, uniqueness, resolvable links, and required template sections, but do not infer semantic applicability or a validation profile. Those judgments remain explicit brief evidence and lifecycle review, avoiding a domain-specific requirements engine. + +## Stable Identifiers + +### Feature IDs + +| Prefix | Meaning | Used in | +| --- | --- | --- | +| `MET-*` | outcome-метрики | `brief.md` | +| `REQ-*` | scope и обязательные capability | `brief.md` | +| `NS-*` | non-scope | `brief.md` | +| `ASM-*` | assumptions и рабочие предпосылки | `brief.md` | +| `CON-*` | ограничения problem space | `brief.md` | +| `DEC-*` | unresolved blocking decisions | `brief.md` | +| `EC-*` | exit criteria | `brief.md` | +| `SC-*` | acceptance scenarios | `brief.md` | +| `NEG-*` | negative / edge test cases | `brief.md` | +| `CHK-*` | проверки | `brief.md`, `implementation-plan.md` | +| `EVID-*` | evidence-артефакты | `brief.md`, `implementation-plan.md` | +| `RJ-*` | rejection rules | `brief.md`, `implementation-plan.md` | + +### Solution IDs + +| Prefix | Meaning | Used in | +| --- | --- | --- | +| `SOL-*` | solution elements / selected design blocks | `design.md` | +| `ALT-*` | considered alternatives | `design.md` | +| `TRD-*` | trade-offs | `design.md` | +| `C4-*` | C4 applicability decision, model levels, elements или relationships | `design.md` | +| `SD-*` | accepted feature-local solution decisions | `design.md` | +| `INV-*` | solution invariants | `design.md` или delegated constituent | +| `CTR-*` | concrete solution contracts | `design.md` или delegated constituent | +| `FM-*` | solution-level failure modes | `design.md` или delegated constituent | +| `RB-*` | rollout / backout stages | `design.md` или delegated constituent | + +### Plan IDs + +| Prefix | Meaning | Used in | +| --- | --- | --- | +| `GRND-*` | grounding evidence о текущем repository state, existing patterns и test surfaces | `implementation-plan.md` | +| `PRE-*` | preconditions | `implementation-plan.md` | +| `OQ-*` | unresolved questions / ambiguities | `implementation-plan.md` | +| `WS-*` | workstreams | `implementation-plan.md` | +| `AG-*` | approval gates for risky actions | `implementation-plan.md` | +| `STEP-*` | атомарные шаги | `implementation-plan.md` | +| `PAR-*` | параллелизуемые блоки | `implementation-plan.md` | +| `CP-*` | checkpoints | `implementation-plan.md` | +| `ER-*` | execution risks | `implementation-plan.md` | +| `STOP-*` | stop conditions / fallback | `implementation-plan.md` | + +### Support IDs + +| Prefix | Meaning | Used in | +| --- | --- | --- | +| `SURF-*` | runtime surfaces / entrypoints / concrete render or processing surfaces | `runtime-surfaces.md` | +| `MAP-*` | semantic mapping rows or mapping rules | `runtime-surfaces.md` | +| `UI-*` | interface screens, states, controls or interaction elements | `ui-reference/README.md` | +| `FUC-*` | derived feature-local use cases | `use-cases/README.md` | +| `TC-*` | derived test case candidates | `use-cases/README.md`, support docs | +| `SEQ-*` | sequence branches, temporal rules or interaction paths | `diagrams/-sequence.md`, embedded sequence views | + +### Required Minimum + +1. Любой canonical `brief.md` использует как минимум `REQ-*`, `NS-*`, `SC-*`, `CHK-*`, `EVID-*`. +2. Любой `brief.md` со `status: active` задает хотя бы один explicit test case через `SC-*`. +3. `brief.md` может использовать только минимальный problem-space набор для compact feature package или расширенный набор feature IDs по необходимости; отдельные problem-space templates не используются. +4. Любой required `design.md` использует как минимум один `SOL-*`, один `C4-*` decision, Architecture Coverage Decision и Design Verification selection и связывает solution refs минимум с одним `REQ-*` из sibling `brief.md`. +5. Любой `design.md` фиксирует selection rationale для C4 applicability; выбранные C4 views используют `C4-*` и связываются с `SOL-*`, `SD-*`, `CTR-*`, `INV-*` или ADR refs. +6. Любой `design.md`, где есть принятые feature-local решения, использует `SD-*`; `ALT-*`, `TRD-*`, `CTR-*`, `INV-*`, `FM-*` и `RB-*` применяются только когда соответствующая solution-semantics действительно нужна. +7. Любой optional support doc использует только local support IDs и traceability к canonical refs; он не вводит новые canonical `REQ-*`, `SC-*`, `CHK-*` или `EVID-*`. +8. Любой `implementation-plan.md` использует как минимум `GRND-*`, `PRE-*`, `STEP-*`, `CHK-*`, `EVID-*`; при наличии ambiguity или human approval gates используются `OQ-*` и `AG-*`. +9. Any new active `brief.md` records applicability for every baseline class and the minimum fields for each applicable `REQ-*`. + +### Traceability Contract + +1. Scope в `brief.md` фиксируется через `REQ-*`, non-scope через `NS-*`. +2. Verify в `brief.md` связывает `REQ-*` с test cases через `Acceptance Scenarios`, feature-specific `NEG-*`, `Traceability matrix`, `Test matrix` и `Evidence contract`. +3. `design.md`, если есть, связывает `REQ-*` из `brief.md` с `SOL-*`, `ALT-*`, `TRD-*`, `C4-*`, `SD-*`, `CTR-*`, `INV-*`, `FM-*`, `RB-*` и accepted ADR refs. +4. `implementation-plan.md` ссылается на canonical IDs из `brief.md` и, если есть, применимые `SOL-*`, `C4-*`, `SD-*`, `CTR-*`, `INV-*`, `FM-*`, `RB-*` и accepted ADR refs в Design Realization Mapping и `Implements`; `Verifies` содержит связанные `CHK-*`, а `Evidence IDs` — подтверждающие `EVID-*`, образуя trace chain от canonical ref до evidence. +5. The plan maps every changed implementation/test/config surface to a `REQ-*` or explicit supporting rationale using exact path plus symbol/section. +6. Если sequencing блокируется неизвестностью, план фиксирует её как `OQ-*`, а не прячет в prose. +7. Если выполнение требует человеческого подтверждения для рискованных действий, план фиксирует это через `AG-*`. +8. Если design или to-be C4 architecture model меняется после `Solution Ready`, сначала обновляется непосредственный owner из Design Pack manifest или external dependency, затем root manifest и план. + +## Worked Traceability Examples + +| Feature kind | Requirement → realization chain | +| --- | --- | +| User-facing | `REQ-01` accessibility: “keyboard focus is visible on every dialog control” → `SC-01` keyboard journey → `CTR-01` UI contract → `web/dialog.tsx#Dialog` → `STEP-01` → `CHK-01` browser test → `EVID-01` CI result. | +| Contract / integration | `REQ-02` interface: “webhook is signed with HMAC-SHA256” → `EC-02` → `CTR-02` → `services/webhook.go#SignPayload` → `STEP-02` → `CHK-02` contract test → `EVID-02` CI result. | +| Infrastructure / operations | `REQ-03` operational: “rollback completes within one deploy unit” → `SC-03` rollback drill → `RB-01` → `infra/deploy.yaml#rollback` → `STEP-03` → `CHK-03` staging drill → `EVID-03` run record. | + +## Migration And Compatibility + +Existing feature packages remain valid: their mnemonic IDs retain their current meanings and are not silently reclassified or renamed. New active packages use the applicability matrix and fields above. An existing package adds only the applicable decision rows and trace links when it next materially changes; unknown legacy coverage is recorded as a gap or follow-up, never fabricated. diff --git a/template/memory-bank/flows/feature.md b/template/memory-bank/flows/feature.md index 2bba038..4d690b3 100644 --- a/template/memory-bank/flows/feature.md +++ b/template/memory-bank/flows/feature.md @@ -8,6 +8,7 @@ derived_from: - ../dna/frontmatter.md - routing.md - priming/context-priming.md + - feature-requirements.md - ../engineering/validation-profiles.md canonical_for: - feature_directory_structure @@ -24,12 +25,6 @@ canonical_for: - feature_architecture_coverage_rules - feature_connector_description_rules - feature_design_verification_rules - - feature_identifier_taxonomy - - feature_requirement_taxonomy - - feature_requirement_traceability_rules - - solution_identifier_taxonomy - - feature_plan_identifier_taxonomy - - feature_traceability_rules - feature_decomposition_principle - feature_grounding_gate - feature_design_layer_definition @@ -67,7 +62,7 @@ immutable revision и `GRND-*` evidence. 7. `design.md` появляется только после `Problem Ready` и только если `brief.md` фиксирует `Design required: yes`. 8. `implementation-plan.md` — derived execution-документ. В новых feature packages он не должен существовать, пока upstream owners не готовы: `brief.md` active и, если design required, весь design pack прошёл `Solution Ready`. 9. Для canonical `brief.md`, canonical `design.md`, feature-level `README.md` и `implementation-plan.md` используй wrapper-шаблоны из `memory-bank/flows/templates/feature/`: сам template-файл имеет `doc_function: template`, а frontmatter/body инстанцируемого документа живут внутри embedded template contract. -10. Смысл стабильных идентификаторов (`REQ-*`, `SOL-*`, `SD-*`, `STEP-*` и т.д.) задается в секции «Stable Identifiers» ниже. +10. Смысл стабильных идентификаторов (`REQ-*`, `SOL-*`, `SD-*`, `STEP-*` и т.д.) задается в [`Feature Requirements, Identifiers And Traceability`](feature-requirements.md#stable-identifiers). 11. Acceptance scenarios (`SC-*`) покрывают delivery-unit end-to-end: для пользовательского slice — от входного события до наблюдаемого результата через все затронутые слои; для infrastructure/engineering/operations change — от system, operator или pipeline trigger до observable operational outcome. Тестирование отдельного слоя в изоляции допустимо как implementation detail плана, но не заменяет end-to-end acceptance. 12. **Связь с task tracker.** При создании feature package агент обязан добавить в исходную задачу или ticket ссылку на `brief.md`, а после появления downstream-документов — ссылки на существующие `design.md` и `implementation-plan.md`. 13. **Source-template exception.** When this repository is itself changing only its generic `template/` payload and its root `memory-bank/` is a managed downstream installation, do not create a project-specific feature package or modify that managed installation solely to mirror the delivery. The routed issue/task record is the brief-equivalent canonical carrier for scope, requirement classes, validation profile, acceptance, evidence, and lifecycle-gate decisions; the PR links back to it. This exception does not apply to a downstream project using the template: its feature delivery still uses `memory-bank/features/FT-XXX/`. @@ -255,6 +250,7 @@ flowchart LR - [ ] `brief.md` → `status: active` - [ ] секция `What` содержит ≥ 1 `REQ-*` и ≥ 1 `NS-*` +- [ ] для каждого baseline requirement class зафиксировано `applicable`, обоснованное `not-applicable` или `covered-upstream` с canonical ref по [`feature-requirements.md`](feature-requirements.md) - [ ] секция `Verify` содержит ≥ 1 `SC-*` - [ ] каждый `REQ-*` прослеживается к ≥ 1 `SC-*` через traceability matrix - [ ] секция `Verify` содержит ≥ 1 `CHK-*` и ≥ 1 `EVID-*` @@ -400,123 +396,42 @@ Canonical testing policy живёт в [../engineering/testing-policy.md](../eng ## Stable Identifiers -## Requirement Taxonomy And Traceability - -`brief.md` owns the feature requirement inventory. A requirement is an externally needed outcome or condition—not a design choice, task, test, or evidence. Keep `REQ-*` as its stable identifier and record a mandatory class field; do not introduce a parallel `FR-*`/`NFR-*` namespace. `MET-*` is a goal or observed metric, `CON-*` a boundary, `EC-*` an acceptance verdict, and `CHK-*`/`EVID-*` proof. Each may link to a `REQ-*`, but none replaces it. - -For every baseline class, the brief records `applicable`, `not-applicable` with a rationale, or `covered-upstream` with its canonical reference. Functional is always applicable; the decision row itself is mandatory for all other classes. The validation profile changes verification depth, not classification. A triggered class gets a `REQ-*`; a shared fact stays in its upstream product, domain, policy, or regulatory owner. - -| Class | Level | Canonical owner / artifact | Applicability trigger | Measurement, verification, and evidence | Example / anti-example | -| --- | --- | --- | --- | --- | --- | -| stakeholder / product | stakeholder/product | shared product, PRD, or use case; otherwise `brief.md` | delivery outcome is stakeholder-specific | validate scenario outcome with its evidence | operator completes intake / internal implementation preference | -| functional | feature/system | `brief.md` `REQ-*` | always | scenario, check, and evidence | system shall accept a submission / use PostgreSQL | -| performance | feature/system/component | `brief.md` `REQ-*` | latency, throughput, capacity, or resource target | numeric threshold, repeatable measurement, report | p95 under 200 ms / “fast” | -| quality attribute | feature/system/component | `brief.md` `REQ-*` | availability, reliability, consistency, recovery, usability, maintainability, etc. | measurable criterion, method, and result carrier | recover within 15 min / add retries | -| interface | feature/system boundary | `brief.md` `REQ-*`, realized by `CTR-*` | API, CLI, event, UI, or external-system boundary | contract/interaction check and sample or CI result | webhook returns signed payload / handler class name | -| data | feature/system boundary | `brief.md` `REQ-*`, realized by `CTR-*` | schema, format, retention, integrity, or migration boundary | data/contract check and migration evidence | retain audit fields 365 days / add a column | -| security | feature/system boundary | `brief.md` `REQ-*`, controls in design | trust, auth, secret, sensitive-data, or threat trigger | analysis plus control check/evidence | only owner may export / choose OAuth library | -| safety | feature/system boundary | `brief.md` `REQ-*`, controls in design | harm, hazardous operation, or safety-critical failure trigger | hazard/failure check and result | stop device on sensor fault / standard exception wording | -| regulatory / compliance | stakeholder/product or system | policy/regulation upstream or `brief.md` | applicable obligation | procedure/check evidence | retain consent record / team style preference | -| operational | feature/system/component | `brief.md` `REQ-*`, solution/runbook in design | operator, observability, support, backup, or recovery trigger | runbook/check evidence | alert includes correlation ID / refactor package name | -| compatibility | feature/system boundary | `brief.md` `REQ-*`, mechanism in design | versioned consumer, migration, or legacy behavior trigger | compatibility matrix/contract check | v1 client remains supported / latest SDK only | -| deployment / rollout | feature/system operation | `brief.md` `REQ-*`, `RB-*` in design | staged release, flag, migration, rollback, or infra delivery trigger | rollout/backout evidence | rollback within one deploy unit / create a new module | -| constraint | any applicable level | `CON-*` in `brief.md` | imposed budget, technology, policy, date, or boundary | link testable proof where possible | must use approved region / prefer a pattern | -| verification / acceptance | feature delivery | `SC-*`, `EC-*`, `CHK-*`, `EVID-*` in `brief.md` | required for each applicable requirement; is proof, not a requirement class | method, acceptance verdict, and evidence carrier | SC proves export result / “add a test” as a requirement | - -Every applicable `REQ-*` records: class, normative measurable statement (a threshold where meaningful), source/rationale, priority, accountable owner, verification method, acceptance/check/evidence links, and realization link. Goals are `MET-*`; assumptions are `ASM-*`; constraints are `CON-*`; selected decisions, invariants, and contracts are `SD-*`/`INV-*`/`CTR-*`; acceptance is `EC-*`; evidence records a result only. - -Required chain: `upstream source → REQ-* → EC/SC → selected solution/contract or design-not-required decision → exact repository path + symbol/config section → STEP-* → CHK-* → EVID-* → review/CI result`. Each changed implementation, test, or configuration surface maps back to a `REQ-*` or an explicit supporting/necessary rationale. Paths are repository-relative and name a symbol, heading, or configuration key; a glob or module-only label is not an exact target. Lifecycle artifact review checks the chain in both directions: no orphan requirement, dangling link, duplicate owner, accepted design fact without realization target, or unexplained changed surface. +The canonical registry moved to +[Feature Requirements, Identifiers And Traceability](feature-requirements.md#stable-identifiers). +The headings below remain as compatibility bridges for existing deep links. -Lint and doctor remain structural: they may validate ID format, uniqueness, resolvable links, and required template sections, but do not infer semantic applicability or a validation profile. Those judgments remain explicit brief evidence and lifecycle review, avoiding a domain-specific requirements engine. - -### Worked Traceability Examples - -| Feature kind | Requirement → realization chain | -| --- | --- | -| User-facing | `REQ-01` accessibility: “keyboard focus is visible on every dialog control” → `SC-01` keyboard journey → `CTR-01` UI contract → `web/dialog.tsx#Dialog` → `STEP-01` → `CHK-01` browser test → `EVID-01` CI result. | -| Contract / integration | `REQ-02` interface: “webhook is signed with HMAC-SHA256” → `EC-02` → `CTR-02` → `services/webhook.go#SignPayload` → `STEP-02` → `CHK-02` contract test → `EVID-02` CI result. | -| Infrastructure / operations | `REQ-03` operational: “rollback completes within one deploy unit” → `SC-03` rollback drill → `RB-01` → `infra/deploy.yaml#rollback` → `STEP-03` → `CHK-03` staging drill → `EVID-03` run record. | - -### Migration And Compatibility +## Requirement Taxonomy And Traceability -Existing feature packages remain valid: their mnemonic IDs retain their current meanings and are not silently reclassified or renamed. New active packages use the applicability matrix and fields above. An existing package adds only the applicable decision rows and trace links when it next materially changes; unknown legacy coverage is recorded as a gap or follow-up, never fabricated. +See [Requirement Taxonomy And Traceability](feature-requirements.md#requirement-taxonomy-and-traceability). ### Feature IDs -| Prefix | Meaning | Used in | -| --- | --- | --- | -| `MET-*` | outcome-метрики | `brief.md` | -| `REQ-*` | scope и обязательные capability | `brief.md` | -| `NS-*` | non-scope | `brief.md` | -| `ASM-*` | assumptions и рабочие предпосылки | `brief.md` | -| `CON-*` | ограничения problem space | `brief.md` | -| `DEC-*` | unresolved blocking decisions | `brief.md` | -| `EC-*` | exit criteria | `brief.md` | -| `SC-*` | acceptance scenarios | `brief.md` | -| `NEG-*` | negative / edge test cases | `brief.md` | -| `CHK-*` | проверки | `brief.md`, `implementation-plan.md` | -| `EVID-*` | evidence-артефакты | `brief.md`, `implementation-plan.md` | -| `RJ-*` | rejection rules | `brief.md`, `implementation-plan.md` | +See [Feature IDs](feature-requirements.md#feature-ids). ### Solution IDs -| Prefix | Meaning | Used in | -| --- | --- | --- | -| `SOL-*` | solution elements / selected design blocks | `design.md` | -| `ALT-*` | considered alternatives | `design.md` | -| `TRD-*` | trade-offs | `design.md` | -| `C4-*` | C4 applicability decision, model levels, elements или relationships | `design.md` | -| `SD-*` | accepted feature-local solution decisions | `design.md` | -| `INV-*` | solution invariants | `design.md` или delegated constituent | -| `CTR-*` | concrete solution contracts | `design.md` или delegated constituent | -| `FM-*` | solution-level failure modes | `design.md` или delegated constituent | -| `RB-*` | rollout / backout stages | `design.md` или delegated constituent | +See [Solution IDs](feature-requirements.md#solution-ids). ### Plan IDs -| Prefix | Meaning | Used in | -| --- | --- | --- | -| `GRND-*` | grounding evidence о текущем repository state, existing patterns и test surfaces | `implementation-plan.md` | -| `PRE-*` | preconditions | `implementation-plan.md` | -| `OQ-*` | unresolved questions / ambiguities | `implementation-plan.md` | -| `WS-*` | workstreams | `implementation-plan.md` | -| `AG-*` | approval gates for risky actions | `implementation-plan.md` | -| `STEP-*` | атомарные шаги | `implementation-plan.md` | -| `PAR-*` | параллелизуемые блоки | `implementation-plan.md` | -| `CP-*` | checkpoints | `implementation-plan.md` | -| `ER-*` | execution risks | `implementation-plan.md` | -| `STOP-*` | stop conditions / fallback | `implementation-plan.md` | +See [Plan IDs](feature-requirements.md#plan-ids). ### Support IDs -| Prefix | Meaning | Used in | -| --- | --- | --- | -| `SURF-*` | runtime surfaces / entrypoints / concrete render or processing surfaces | `runtime-surfaces.md` | -| `MAP-*` | semantic mapping rows or mapping rules | `runtime-surfaces.md` | -| `UI-*` | interface screens, states, controls or interaction elements | `ui-reference/README.md` | -| `FUC-*` | derived feature-local use cases | `use-cases/README.md` | -| `TC-*` | derived test case candidates | `use-cases/README.md`, support docs | -| `SEQ-*` | sequence branches, temporal rules or interaction paths | `diagrams/-sequence.md`, embedded sequence views | +See [Support IDs](feature-requirements.md#support-ids). ### Required Minimum -1. Любой canonical `brief.md` использует как минимум `REQ-*`, `NS-*`, `SC-*`, `CHK-*`, `EVID-*`. -2. Любой `brief.md` со `status: active` задает хотя бы один explicit test case через `SC-*`. -3. `brief.md` может использовать только минимальный problem-space набор для compact feature package или расширенный набор feature IDs по необходимости; отдельные problem-space templates не используются. -4. Любой required `design.md` использует как минимум один `SOL-*`, один `C4-*` decision, Architecture Coverage Decision и Design Verification selection и связывает solution refs минимум с одним `REQ-*` из sibling `brief.md`. -5. Любой `design.md` фиксирует selection rationale для C4 applicability; выбранные C4 views используют `C4-*` и связываются с `SOL-*`, `SD-*`, `CTR-*`, `INV-*` или ADR refs. -6. Любой `design.md`, где есть принятые feature-local решения, использует `SD-*`; `ALT-*`, `TRD-*`, `CTR-*`, `INV-*`, `FM-*` и `RB-*` применяются только когда соответствующая solution-semantics действительно нужна. -7. Любой optional support doc использует только local support IDs и traceability к canonical refs; он не вводит новые canonical `REQ-*`, `SC-*`, `CHK-*` или `EVID-*`. -8. Любой `implementation-plan.md` использует как минимум `GRND-*`, `PRE-*`, `STEP-*`, `CHK-*`, `EVID-*`; при наличии ambiguity или human approval gates используются `OQ-*` и `AG-*`. -9. Any new active `brief.md` records applicability for every baseline class and the minimum fields for each applicable `REQ-*`. +See [Required Minimum](feature-requirements.md#required-minimum). ### Traceability Contract -1. Scope в `brief.md` фиксируется через `REQ-*`, non-scope через `NS-*`. -2. Verify в `brief.md` связывает `REQ-*` с test cases через `Acceptance Scenarios`, feature-specific `NEG-*`, `Traceability matrix`, `Test matrix` и `Evidence contract`. -3. `design.md`, если есть, связывает `REQ-*` из `brief.md` с `SOL-*`, `ALT-*`, `TRD-*`, `C4-*`, `SD-*`, `CTR-*`, `INV-*`, `FM-*`, `RB-*` и accepted ADR refs. -4. `implementation-plan.md` ссылается на canonical IDs из `brief.md` и, если есть, применимые `SOL-*`, `C4-*`, `SD-*`, `CTR-*`, `INV-*`, `FM-*`, `RB-*` и accepted ADR refs в Design Realization Mapping и `Implements`; `Verifies` содержит связанные `CHK-*`, а `Evidence IDs` — подтверждающие `EVID-*`, образуя trace chain от canonical ref до evidence. -5. The plan maps every changed implementation/test/config surface to a `REQ-*` or explicit supporting rationale using exact path plus symbol/section. -6. Если sequencing блокируется неизвестностью, план фиксирует её как `OQ-*`, а не прячет в prose. -7. Если выполнение требует человеческого подтверждения для рискованных действий, план фиксирует это через `AG-*`. -8. Если design или to-be C4 architecture model меняется после `Solution Ready`, сначала обновляется непосредственный owner из Design Pack manifest или external dependency, затем root manifest и план. +See [Traceability Contract](feature-requirements.md#traceability-contract). + +### Worked Traceability Examples + +See [Worked Traceability Examples](feature-requirements.md#worked-traceability-examples). + +### Migration And Compatibility + +See [Migration And Compatibility](feature-requirements.md#migration-and-compatibility). diff --git a/template/memory-bank/flows/priming/epic.yaml b/template/memory-bank/flows/priming/epic.yaml index 32614f6..9870911 100644 --- a/template/memory-bank/flows/priming/epic.yaml +++ b/template/memory-bank/flows/priming/epic.yaml @@ -21,3 +21,4 @@ stages: execution_handoff: - memory-bank/epics//*.md - memory-bank/flows/feature.md + - memory-bank/flows/feature-requirements.md diff --git a/template/memory-bank/flows/priming/feature.yaml b/template/memory-bank/flows/priming/feature.yaml index c51d445..f7e844f 100644 --- a/template/memory-bank/flows/priming/feature.yaml +++ b/template/memory-bank/flows/priming/feature.yaml @@ -2,6 +2,7 @@ version: 1 process: feature stages: bootstrap_brief: + - memory-bank/flows/feature-requirements.md - memory-bank/flows/feature-artifact-catalog.md - memory-bank/features/README.md - memory-bank/prd/*.md diff --git a/template/memory-bank/flows/templates/feature/brief.md b/template/memory-bank/flows/templates/feature/brief.md index da05780..9d883ca 100644 --- a/template/memory-bank/flows/templates/feature/brief.md +++ b/template/memory-bank/flows/templates/feature/brief.md @@ -5,6 +5,7 @@ doc_function: template purpose: Governed wrapper-шаблон для canonical `brief.md` в AI-driven development. Фиксирует, как инстанцировать problem-space intent, scope и machine-checkable verify без смешения wrapper и целевого frontmatter. derived_from: - ../../feature.md + - ../../feature-requirements.md - ../../feature-artifact-catalog.md - ../../../dna/frontmatter.md - ../../../engineering/testing-policy.md @@ -28,7 +29,7 @@ canonical_for: Optional companions выбирай по [Feature Artifact Catalog](../../feature-artifact-catalog.md). Не копируй весь каталог в feature и не создавай placeholders: Artifact Routing Decision перечисляет только выбранные artifacts и material omissions, которые важно объяснить reviewers. -Используй стабильные идентификаторы по taxonomy из [../../feature.md#stable-identifiers](../../feature.md#stable-identifiers). +Используй стабильные идентификаторы по taxonomy из [../../feature-requirements.md#stable-identifiers](../../feature-requirements.md#stable-identifiers). ### Frontmatter Quick Ref @@ -55,6 +56,7 @@ doc_function: canonical purpose: "Canonical brief для delivery-единицы. Фиксирует problem space, scope, validation profile и verify без смешения с solution space или execution plan." derived_from: - ../../flows/feature.md + - ../../flows/feature-requirements.md # Optional: # - ../../product/context.md # - ../../domain/rules.md @@ -77,7 +79,7 @@ must_not_define: ### Requirement applicability and classification -For every baseline class in [Feature Flow](../../feature.md#requirement-taxonomy-and-traceability), select `applicable`, `not-applicable` with rationale, or `covered-upstream` with reference. Do not create `FR-*`/`NFR-*`; record the class on `REQ-*`. +For every baseline class in [Feature Requirements, Identifiers And Traceability](../../feature-requirements.md#requirement-taxonomy-and-traceability), select `applicable`, `not-applicable` with rationale, or `covered-upstream` with reference. Do not create `FR-*`/`NFR-*`; record the class on `REQ-*`. | Class | Decision | Trigger / rationale / upstream reference | Requirement IDs | | --- | --- | --- | --- | diff --git a/template/memory-bank/flows/templates/feature/implementation-plan.md b/template/memory-bank/flows/templates/feature/implementation-plan.md index cecc20a..b70c4de 100644 --- a/template/memory-bank/flows/templates/feature/implementation-plan.md +++ b/template/memory-bank/flows/templates/feature/implementation-plan.md @@ -5,6 +5,7 @@ doc_function: template purpose: Governed wrapper-шаблон плана имплементации. Фиксирует, как инстанцировать execution-документ без переопределения canonical problem или solution facts и без смешения wrapper с целевым `implementation-plan.md`. derived_from: - ../../feature.md + - ../../feature-requirements.md - ../../feature-artifact-catalog.md - ../../priming/context-priming.md - ../../../dna/frontmatter.md @@ -34,7 +35,7 @@ template_target_path: ../../../features/FT-XXX/implementation-plan.md Plan Ready artifact review проверяет этот документ как governed artifact до начала execution. Его verdict хранится вне reviewed plan и фиксирует reviewer, grounded repository revision, candidate revisions canonical owners/plan, findings/dispositions и clean verdict. Artifact review не является review реализации и не заменяет последующий implementation/code review. -Для ссылок внутри плана используй стабильные идентификаторы по taxonomy из [../../feature.md#stable-identifiers](../../feature.md#stable-identifiers). +Для ссылок внутри плана используй стабильные идентификаторы по taxonomy из [../../feature-requirements.md#stable-identifiers](../../feature-requirements.md#stable-identifiers). Если неизвестность меняет scope, acceptance criteria или evidence contract, она сначала поднимается upstream в sibling `brief.md`. Если неизвестность меняет selected design, architecture coverage, C4 architecture model, accepted local decisions, contracts, invariants, failure modes или rollout/backout semantics, она сначала поднимается в required sibling `design.md`, delegated contract или ADR и только после этого фигурирует в плане. From 5f83e605357ed5af4b4fdf55dde2ab7441709c3d Mon Sep 17 00:00:00 2001 From: Danil Pismenny Date: Fri, 14 Aug 2026 05:31:31 +0300 Subject: [PATCH 3/5] docs: clarify feature requirement gates --- template/memory-bank/flows/feature-requirements.md | 2 +- template/memory-bank/flows/feature.md | 11 +++++++++++ .../memory-bank/flows/templates/feature/design.md | 8 ++++---- .../flows/templates/feature/implementation-plan.md | 2 +- 4 files changed, 17 insertions(+), 6 deletions(-) diff --git a/template/memory-bank/flows/feature-requirements.md b/template/memory-bank/flows/feature-requirements.md index 3091f48..b7694d8 100644 --- a/template/memory-bank/flows/feature-requirements.md +++ b/template/memory-bank/flows/feature-requirements.md @@ -33,7 +33,7 @@ problem, solution и execution layers. Lifecycle и transition gates остаю `brief.md` owns the feature requirement inventory. A requirement is an externally needed outcome or condition—not a design choice, task, test, or evidence. Keep `REQ-*` as its stable identifier and record a mandatory class field; do not introduce a parallel `FR-*`/`NFR-*` namespace. `MET-*` is a goal or observed metric, `CON-*` a boundary, `EC-*` an acceptance verdict, and `CHK-*`/`EVID-*` proof. Each may link to a `REQ-*`, but none replaces it. -For every baseline class, the brief records `applicable`, `not-applicable` with a rationale, or `covered-upstream` with its canonical reference. Functional is always applicable; the decision row itself is mandatory for all other classes. The validation profile changes verification depth, not classification. A triggered class gets a `REQ-*`; a shared fact stays in its upstream product, domain, policy, or regulatory owner. +For every baseline class, the brief records `applicable`, `not-applicable` with a rationale, or `covered-upstream` with its canonical reference. Functional is always applicable; the decision row itself is mandatory for all other classes. The validation profile changes verification depth, not classification. A triggered requirement class from stakeholder/product through deployment/rollout gets a `REQ-*`; the constraint and verification/acceptance rows use `CON-*` and `SC-*`/`EC-*`/`CHK-*`/`EVID-*` as classified supporting contract, not synthetic requirements. A shared fact stays in its upstream product, domain, policy, or regulatory owner. | Class | Level | Canonical owner / artifact | Applicability trigger | Measurement, verification, and evidence | Example / anti-example | | --- | --- | --- | --- | --- | --- | diff --git a/template/memory-bank/flows/feature.md b/template/memory-bank/flows/feature.md index 64291c8..c341bbe 100644 --- a/template/memory-bank/flows/feature.md +++ b/template/memory-bank/flows/feature.md @@ -303,6 +303,17 @@ flowchart LR Каждый gate — набор проверяемых предикатов. Переход допустим тогда и только тогда, когда все предикаты истинны. +### Source-Template Gate Adaptation + +Когда применяется source-template exception из [Package Rules](#package-rules), +feature package намеренно не создаётся. Это отдельный вариант тех же gates, а +не bypass: + +1. Routed issue/task carrier заменяет `README.md` и `brief.md` и содержит те же problem-space facts: scope/non-scope, requirement applicability, acceptance/evidence contract, validation profile, Design Requirement Decision и lifecycle state. +2. При `Design required: yes` selected solution и применимые design predicates фиксируются в изменяемых governed owners, accepted ADR или linked issue/PR design record; при `no` carrier хранит rationale. +3. Plan/Execution predicates проверяются по repository-approved issue/PR/orchestration record: immutable grounding revision, exact targets, steps, checks, evidence, approvals и review verdicts остаются обязательными, хотя `implementation-plan.md` не создаётся. +4. Только predicates существования и publication/lifecycle status файлов package заменяются explicit exception evidence. Semantic, ownership, validation, Git, CI и closure predicates выполняются без ослабления. + ### Bootstrap Feature Package - [ ] `README.md` создан по шаблону `templates/feature/README.md` diff --git a/template/memory-bank/flows/templates/feature/design.md b/template/memory-bank/flows/templates/feature/design.md index 054ec1b..4277322 100644 --- a/template/memory-bank/flows/templates/feature/design.md +++ b/template/memory-bank/flows/templates/feature/design.md @@ -143,7 +143,10 @@ design. Используй только ссылки на canonical facts; дл ## Selected Solution -## Requirement realization boundary +- `SOL-01` Выбранный элемент решения и почему он закрывает `REQ-*`. +- `SOL-02` Второй элемент решения, если нужен. + +### Requirement realization boundary `brief.md` owns requirements and acceptance. Map its applicable `REQ-*` to selected solution facts here, without adding requirements. @@ -151,9 +154,6 @@ design. Используй только ссылки на canonical facts; дл | --- | --- | --- | --- | --- | | `REQ-01` | interface | `SOL-01`, `CTR-01` | `implementation-plan.md` | `CHK-01`, `EVID-01` | -- `SOL-01` Выбранный элемент решения и почему он закрывает `REQ-*`. -- `SOL-02` Второй элемент решения, если нужен. - ## Alternatives Considered | Alternative ID | Option | Why not selected | diff --git a/template/memory-bank/flows/templates/feature/implementation-plan.md b/template/memory-bank/flows/templates/feature/implementation-plan.md index d9324d0..cc0fb37 100644 --- a/template/memory-bank/flows/templates/feature/implementation-plan.md +++ b/template/memory-bank/flows/templates/feature/implementation-plan.md @@ -190,7 +190,7 @@ Use repository-relative paths and a symbol, heading, or configuration key. A cha | Requirement or supporting ref | Exact implementation / test / config path + symbol/section | Change role | Steps | Checks / evidence | | --- | --- | --- | --- | --- | | `REQ-01` | `path/file.ext#Symbol` | direct realization | `STEP-01` | `CHK-01`, `EVID-01` | -| `SUP-01` | `path/test.ext#test_name` | supporting: why required | `STEP-02` | `CHK-02`, `EVID-02` | +| supporting rationale: regression coverage for `REQ-01` | `path/test.ext#test_name` | supporting: why required | `STEP-02` | `CHK-02`, `EVID-02` | ## Workstreams From 79de299fe939ba7efc563ac72fa846af7334bac5 Mon Sep 17 00:00:00 2001 From: Danil Pismenny Date: Fri, 14 Aug 2026 05:38:50 +0300 Subject: [PATCH 4/5] docs: keep feature policy generic --- .../engineering/validation-profiles.md | 2 +- template/memory-bank/flows/feature.md | 24 +++++-------------- .../flows/templates/feature/brief.md | 2 +- 3 files changed, 8 insertions(+), 20 deletions(-) diff --git a/template/memory-bank/engineering/validation-profiles.md b/template/memory-bank/engineering/validation-profiles.md index ad42599..8fc4cb0 100644 --- a/template/memory-bank/engineering/validation-profiles.md +++ b/template/memory-bank/engineering/validation-profiles.md @@ -99,7 +99,7 @@ Profile decision записывается ровно один раз; downstream | Flow | Canonical owner | Правило | | --- | --- | --- | | Small Change | issue/task routing record; draft PR только если tracker нельзя обновить | Record содержит profile, triggers/rationale и approval ref при downgrade. | -| Feature | `memory-bank/features/FT-XXX/brief.md`; for the source-template exception in Feature Flow, the routed issue/task record | `implementation-plan.md` реализует contract через suites/checkpoints, но не дублирует решение. The exception carrier records the same minimum decision fields without modifying a managed downstream installation. | +| Feature | `memory-bank/features/FT-XXX/brief.md` | `implementation-plan.md` реализует contract через suites/checkpoints, но не дублирует решение. | | Bug Fix | bug report или связанная delivery task; draft PR только как fallback | Reproduction, regression plan и evidence исполняют выбранный profile. | | Refactoring | исходная task; draft PR только как fallback | Profile учитывает blast radius и critical behavior, которое нужно сохранить. | | Incident / PIR | Не назначается containment/PIR record | Permanent remediation и prevention items получают profile после отдельного Task Routing. Incident safety gates продолжают действовать независимо. | diff --git a/template/memory-bank/flows/feature.md b/template/memory-bank/flows/feature.md index c341bbe..3167505 100644 --- a/template/memory-bank/flows/feature.md +++ b/template/memory-bank/flows/feature.md @@ -70,13 +70,12 @@ immutable revision и `GRND-*` evidence. 11. Acceptance scenarios (`SC-*`) покрывают delivery-unit end-to-end: для пользовательского slice — от входного события до наблюдаемого результата через все затронутые слои; для infrastructure/engineering/operations change — от system, operator или pipeline trigger до observable operational outcome. Тестирование отдельного слоя в изоляции допустимо как implementation detail плана, но не заменяет end-to-end acceptance. 12. Для observable behavior применяй [`Behavior Specification Practice`](behavior-specification.md): discovery findings маршрутизируются в существующие owners, concrete examples формулируются через `SC-*` / `NEG-*`, а automation связывается через `CHK-*` и `EVID-*`. BDD не вводит отдельный route или `BDD-*` identifiers. 13. **Связь с task tracker.** При создании feature package агент обязан добавить в исходную задачу или ticket ссылку на `brief.md`, а после появления downstream-документов — ссылки на существующие `design.md` и `implementation-plan.md`. -14. **Source-template exception.** When this repository is itself changing only its generic `template/` payload and its root `memory-bank/` is a managed downstream installation, do not create a project-specific feature package or modify that managed installation solely to mirror the delivery. The routed issue/task record is the brief-equivalent canonical carrier for scope, requirement classes, validation profile, acceptance, evidence, and lifecycle-gate decisions; the PR links back to it. This exception does not apply to a downstream project using the template: its feature delivery still uses `memory-bank/features/FT-XXX/`. -15. До Bootstrap / Brief агент обязан прочитать весь текущий `memory-bank/prd/*.md` corpus. Это обязательный context baseline независимо от того, зависит ли feature от конкретного PRD; PRD не заменяет сам feature package. -16. Если фича создает новый устойчивый сценарий проекта или materially changes существующий, соответствующий `UC-*` в `memory-bank/use-cases/` должен быть создан или обновлен до closure. -17. Optional feature-support docs (`runtime-surfaces.md`, `diagrams/-sequence.md`, `ui-reference/README.md`, `use-cases/README.md`) допустимы для сложных фич как grounding / review / traceability aids. Они не становятся canonical owner problem space, solution space, acceptance inventory или execution sequencing. -18. Полное чтение PRD corpus не создаёт semantic dependency от каждого PRD. `brief.md: derived_from` импортирует только фактические upstream-owner references и не копирует весь upstream scope. -19. Если работа крупнее одной delivery-feature и требует общего roadmap, cross-feature risk register или нескольких delivery units, не расширяй feature package: повтори [`Task Routing`](routing.md), выбери [`Epic Flow`](epic.md) и после epic handoff веди каждую утвержденную delivery-единицу как отдельный feature package. -20. Validation profile выбирается в `brief.md` по [`validation-profiles.md`](../engineering/validation-profiles.md). `design.md` может уточнить risk facts, а `implementation-plan.md` разворачивает minimum contract в команды, suites и checkpoints, но ни один из них не дублирует profile decision. The source-template exception records this decision in its issue/task carrier instead. +14. До Bootstrap / Brief агент обязан прочитать весь текущий `memory-bank/prd/*.md` corpus. Это обязательный context baseline независимо от того, зависит ли feature от конкретного PRD; PRD не заменяет сам feature package. +15. Если фича создает новый устойчивый сценарий проекта или materially changes существующий, соответствующий `UC-*` в `memory-bank/use-cases/` должен быть создан или обновлен до closure. +16. Optional feature-support docs (`runtime-surfaces.md`, `diagrams/-sequence.md`, `ui-reference/README.md`, `use-cases/README.md`) допустимы для сложных фич как grounding / review / traceability aids. Они не становятся canonical owner problem space, solution space, acceptance inventory или execution sequencing. +17. Полное чтение PRD corpus не создаёт semantic dependency от каждого PRD. `brief.md: derived_from` импортирует только фактические upstream-owner references и не копирует весь upstream scope. +18. Если работа крупнее одной delivery-feature и требует общего roadmap, cross-feature risk register или нескольких delivery units, не расширяй feature package: повтори [`Task Routing`](routing.md), выбери [`Epic Flow`](epic.md) и после epic handoff веди каждую утвержденную delivery-единицу как отдельный feature package. +19. Validation profile выбирается в `brief.md` по [`validation-profiles.md`](../engineering/validation-profiles.md). `design.md` может уточнить risk facts, а `implementation-plan.md` разворачивает minimum contract в команды, suites и checkpoints, но ни один из них не дублирует profile decision. ## Feature Package Anatomy @@ -303,17 +302,6 @@ flowchart LR Каждый gate — набор проверяемых предикатов. Переход допустим тогда и только тогда, когда все предикаты истинны. -### Source-Template Gate Adaptation - -Когда применяется source-template exception из [Package Rules](#package-rules), -feature package намеренно не создаётся. Это отдельный вариант тех же gates, а -не bypass: - -1. Routed issue/task carrier заменяет `README.md` и `brief.md` и содержит те же problem-space facts: scope/non-scope, requirement applicability, acceptance/evidence contract, validation profile, Design Requirement Decision и lifecycle state. -2. При `Design required: yes` selected solution и применимые design predicates фиксируются в изменяемых governed owners, accepted ADR или linked issue/PR design record; при `no` carrier хранит rationale. -3. Plan/Execution predicates проверяются по repository-approved issue/PR/orchestration record: immutable grounding revision, exact targets, steps, checks, evidence, approvals и review verdicts остаются обязательными, хотя `implementation-plan.md` не создаётся. -4. Только predicates существования и publication/lifecycle status файлов package заменяются explicit exception evidence. Semantic, ownership, validation, Git, CI и closure predicates выполняются без ослабления. - ### Bootstrap Feature Package - [ ] `README.md` создан по шаблону `templates/feature/README.md` diff --git a/template/memory-bank/flows/templates/feature/brief.md b/template/memory-bank/flows/templates/feature/brief.md index c08e6b8..7eba880 100644 --- a/template/memory-bank/flows/templates/feature/brief.md +++ b/template/memory-bank/flows/templates/feature/brief.md @@ -82,7 +82,7 @@ must_not_define: ### Requirement applicability and classification -For every baseline class in [Feature Requirements, Identifiers And Traceability](../../feature-requirements.md#requirement-taxonomy-and-traceability), select `applicable`, `not-applicable` with rationale, or `covered-upstream` with reference. Do not create `FR-*`/`NFR-*`; record the class on `REQ-*`. +For every baseline class in [Feature Requirements, Identifiers And Traceability](../../flows/feature-requirements.md#requirement-taxonomy-and-traceability), select `applicable`, `not-applicable` with rationale, or `covered-upstream` with reference. Do not create `FR-*`/`NFR-*`; record the class on `REQ-*`. | Class | Decision | Trigger / rationale / upstream reference | Requirement IDs | | --- | --- | --- | --- | From 2bf5c0890989d9b64dc31fb5e13e935682ee7b20 Mon Sep 17 00:00:00 2001 From: Danil Pismenny Date: Fri, 14 Aug 2026 05:43:53 +0300 Subject: [PATCH 5/5] docs: align feature traceability stages --- dependency-tree.md | 2 +- template/memory-bank/engineering/testing-policy.md | 1 + template/memory-bank/flows/feature-requirements.md | 2 +- template/memory-bank/flows/templates/feature/brief.md | 10 +++++----- 4 files changed, 8 insertions(+), 7 deletions(-) diff --git a/dependency-tree.md b/dependency-tree.md index f46cb5c..633ea11 100644 --- a/dependency-tree.md +++ b/dependency-tree.md @@ -106,7 +106,7 @@ template/memory-bank/dna/principles.md ### Feature-related Docs - [`template/memory-bank/flows/feature-artifact-catalog.md`](template/memory-bank/flows/feature-artifact-catalog.md) зависит от [`template/memory-bank/flows/feature.md`](template/memory-bank/flows/feature.md) и [`template/memory-bank/flows/feature-requirements.md`](template/memory-bank/flows/feature-requirements.md). -- [`template/memory-bank/engineering/testing-policy.md`](template/memory-bank/engineering/testing-policy.md) зависит от [`template/memory-bank/dna/governance.md`](template/memory-bank/dna/governance.md), [`template/memory-bank/flows/behavior-specification.md`](template/memory-bank/flows/behavior-specification.md), [`template/memory-bank/flows/feature.md`](template/memory-bank/flows/feature.md) и validation profiles. +- [`template/memory-bank/engineering/testing-policy.md`](template/memory-bank/engineering/testing-policy.md) зависит от [`template/memory-bank/dna/governance.md`](template/memory-bank/dna/governance.md), [`template/memory-bank/flows/behavior-specification.md`](template/memory-bank/flows/behavior-specification.md), [`template/memory-bank/flows/feature.md`](template/memory-bank/flows/feature.md), [`template/memory-bank/flows/feature-requirements.md`](template/memory-bank/flows/feature-requirements.md) и validation profiles. - [`template/memory-bank/features/README.md`](template/memory-bank/features/README.md) зависит от [`template/memory-bank/dna/governance.md`](template/memory-bank/dna/governance.md) и [`template/memory-bank/flows/feature.md`](template/memory-bank/flows/feature.md). - [`template/memory-bank/flows/templates/feature/README.md`](template/memory-bank/flows/templates/feature/README.md) зависит от [`template/memory-bank/flows/feature.md`](template/memory-bank/flows/feature.md) и [`template/memory-bank/dna/frontmatter.md`](template/memory-bank/dna/frontmatter.md). - [`template/memory-bank/flows/templates/feature/brief.md`](template/memory-bank/flows/templates/feature/brief.md) зависит от [`template/memory-bank/flows/feature.md`](template/memory-bank/flows/feature.md), [`template/memory-bank/flows/feature-requirements.md`](template/memory-bank/flows/feature-requirements.md), [`template/memory-bank/flows/behavior-specification.md`](template/memory-bank/flows/behavior-specification.md), [`template/memory-bank/dna/frontmatter.md`](template/memory-bank/dna/frontmatter.md) и [`template/memory-bank/engineering/testing-policy.md`](template/memory-bank/engineering/testing-policy.md). diff --git a/template/memory-bank/engineering/testing-policy.md b/template/memory-bank/engineering/testing-policy.md index 415bc66..837f39e 100644 --- a/template/memory-bank/engineering/testing-policy.md +++ b/template/memory-bank/engineering/testing-policy.md @@ -7,6 +7,7 @@ derived_from: - ../dna/governance.md - ../flows/behavior-specification.md - ../flows/feature.md + - ../flows/feature-requirements.md - validation-profiles.md status: active canonical_for: diff --git a/template/memory-bank/flows/feature-requirements.md b/template/memory-bank/flows/feature-requirements.md index b7694d8..9783b0c 100644 --- a/template/memory-bank/flows/feature-requirements.md +++ b/template/memory-bank/flows/feature-requirements.md @@ -52,7 +52,7 @@ For every baseline class, the brief records `applicable`, `not-applicable` with | constraint | any applicable level | `CON-*` in `brief.md` | imposed budget, technology, policy, date, or boundary | link testable proof where possible | must use approved region / prefer a pattern | | verification / acceptance | feature delivery | `SC-*`, `EC-*`, `CHK-*`, `EVID-*` in `brief.md` | required for each applicable requirement; is proof, not a requirement class | method, acceptance verdict, and evidence carrier | SC proves export result / “add a test” as a requirement | -Every applicable `REQ-*` records: class, normative measurable statement (a threshold where meaningful), source/rationale, priority, accountable owner, verification method, acceptance/check/evidence links, and realization link. Goals are `MET-*`; assumptions are `ASM-*`; constraints are `CON-*`; selected decisions, invariants, and contracts are `SD-*`/`INV-*`/`CTR-*`; acceptance is `EC-*`; evidence records a result only. +At `Problem Ready`, every applicable `REQ-*` records: class, normative measurable statement (a threshold where meaningful), source/rationale, priority, accountable owner, verification method, and acceptance/check/evidence contract links. The owning design mapping adds selected-solution refs at `Solution Ready`; the owning plan adds exact realization targets and steps at `Plan Ready`; execution supplies evidence and review/CI results. Do not fabricate or copy those downstream facts into `brief.md` before their owning gate. Goals are `MET-*`; assumptions are `ASM-*`; constraints are `CON-*`; selected decisions, invariants, and contracts are `SD-*`/`INV-*`/`CTR-*`; acceptance is `EC-*`; evidence records a result only. Required chain: `upstream source → REQ-* → EC/SC → selected solution/contract or design-not-required decision → exact repository path + symbol/config section → STEP-* → CHK-* → EVID-* → review/CI result`. Each changed implementation, test, or configuration surface maps back to a `REQ-*` or an explicit supporting/necessary rationale. Paths are repository-relative and name a symbol, heading, or configuration key; a glob or module-only label is not an exact target. Lifecycle artifact review checks the chain in both directions: no orphan requirement, dangling link, duplicate owner, accepted design fact without realization target, or unexplained changed surface. diff --git a/template/memory-bank/flows/templates/feature/brief.md b/template/memory-bank/flows/templates/feature/brief.md index 7eba880..1305390 100644 --- a/template/memory-bank/flows/templates/feature/brief.md +++ b/template/memory-bank/flows/templates/feature/brief.md @@ -240,11 +240,11 @@ Verify должен быть исполнимым. | `EVID-01` | Лог, отчет, скриншот или sample output | verify-runner / human | `artifacts/ft-xxx/verify/chk-01/` | `CHK-01` | | `EVID-02` | Лог, отчет или sample output для negative/edge behavior | verify-runner / human | `artifacts/ft-xxx/verify/chk-02/` | `CHK-02` | -### Requirement-to-realization traceability +### Requirement acceptance traceability -`brief.md` owns the requirement chain; `design.md` owns selected solution facts and the plan supplies the exact target. A supporting change without a direct `REQ-*` needs its explicit rationale. +`brief.md` owns requirements and their acceptance/evidence contract. Selected solution facts belong to `design.md`; exact targets, supporting-change rationale and steps belong to `implementation-plan.md`; execution owns results. Their mappings extend this chain at later gates without copying those facts back into the brief. -| Requirement | Acceptance / check / evidence | Solution or decision | Exact realization target | Supporting rationale / review or CI result | -| --- | --- | --- | --- | --- | -| `REQ-01` | `EC-01`, `SC-01`, `CHK-01`, `EVID-01` | `SOL-01` / design-not-required decision | `path/file.ext#SymbolOrSection` | none / CI URL | +| Requirement | Acceptance | Verification method / check | Evidence contract | +| --- | --- | --- | --- | +| `REQ-01` | `EC-01`, `SC-01` | automated test via `CHK-01` | `EVID-01` | ```