diff --git a/memory-bank/features/FT-117/README.md b/memory-bank/features/FT-117/README.md new file mode 100644 index 0000000..6c5b0e3 --- /dev/null +++ b/memory-bank/features/FT-117/README.md @@ -0,0 +1,39 @@ +--- +title: "FT-117: Autonomous Structured Decision Protocol" +doc_kind: feature +doc_function: index +purpose: "Навигация по project-level feature package issue #117: автономное принятие bounded решений с отдельной проверкой permission на execution gate." +derived_from: + - ../../dna/governance.md + - ../../flows/feature.md + - brief.md +status: active +audience: humans_and_agents +--- + +# FT-117: Autonomous Structured Decision Protocol + +## О разделе + +Feature package фиксирует problem space, selected solution и execution plan для +issue [#117](https://github.com/dapi/memory-bank/issues/117). Scope ограничен +governed Memory Bank documentation: package не добавляет runtime-код, production +configuration или implicit permission на внешние действия. + +## Аннотированный индекс + +- [`brief.md`](brief.md) + Читать первым: canonical problem, scope, acceptance scenarios, validation + profile и verify contract. + +- [`design.md`](design.md) + Читать после brief: selected cross-flow governance solution, ownership, + C4/applicability и 4+1 coverage. + +- [`implementation-plan.md`](implementation-plan.md) + Читать перед recovery acceptance: immutable Git receipts, exact checks, + review gates, checkpoints и stop conditions для existing candidate. + +- [`feature-review-report.md`](feature-review-report.md) + Читать для self-review, independent review history, acceptance coverage и + результатов deterministic documentation checks. diff --git a/memory-bank/features/FT-117/brief.md b/memory-bank/features/FT-117/brief.md new file mode 100644 index 0000000..afc2248 --- /dev/null +++ b/memory-bank/features/FT-117/brief.md @@ -0,0 +1,195 @@ +--- +title: "FT-117: Autonomous Structured Decision Protocol" +doc_kind: feature +doc_function: canonical +purpose: "Canonical problem-space brief для issue #117. Фиксирует автономное принятие bounded решений, границу approval и проверяемый delivery outcome без selected solution details." +derived_from: + - ../../flows/feature.md + - ../../../template/memory-bank/flows/routing.md + - ../../../template/memory-bank/flows/research.md + - ../../../template/memory-bank/engineering/autonomy-boundaries.md + - ../../../template/memory-bank/engineering/validation-profiles.md +status: active +delivery_status: done +audience: humans_and_agents +must_not_define: + - implementation_sequence + - selected_solution_details +--- + +# FT-117: Autonomous Structured Decision Protocol + +## What + +### Problem + +Issue [#117](https://github.com/dapi/memory-bank/issues/117) обнаружила, что +сложность, ambiguity, несколько допустимых подходов и исчерпание review budget +могут преждевременно останавливать агента на Human Gate. Одновременно правила +смешивали decision authority, durable decision record и permission на +внешне-эффективный execution. + +### Outcome + +| Metric ID | Metric | Baseline | Target | Measurement method | +| --- | --- | --- | --- | --- | +| `MET-01` | Покрытие decision/approval contract | Роли и execution permission описаны неполно | Каждое non-trivial решение различает authority source, decision owner, carrier и execution approval | Semantic review canonical docs и deterministic documentation checks | +| `MET-02` | Premature Human Gate triggers | Ambiguity/complexity/review exhaustion могли эскалировать сами по себе | Эскалация только после `Structured Decision Protocol` outcome `escalate` или отдельного execution gate | Review Routing, Bug Fix, Feature и Validation contracts | +| `MET-03` | Проверяемость документации | Cross-flow rules могли расходиться | Priming manifests, links, reachability и doctor проходят без ошибок | Repository validation commands | + +## Scope + +- `REQ-01` Определить обязательный self-contained decision protocol, который + даёт проверяемый результат: автономное продолжение, bounded investigation + или конкретная эскалация. +- `REQ-02` Разделить authority source, accountable decision owner, canonical + carrier, execution approver и approval evidence. +- `REQ-03` Разрешить автономный выбор между допустимыми вариантами на основе + заданного intent, ограничений и проверяемого rationale; близость вариантов + сама по себе не должна создавать Human Gate. +- `REQ-04` Различать unknown, требующий discovery evidence до выбора delivery + route, и implementation-only unknown после выбора route. +- `REQ-05` Ограничить Human Gate authority boundary, material + security/auth/trust/compliance boundary mutation без specific task/policy + authority, external effect, explicit approval policy, missing value judgment + и uncontrollable risk. +- `REQ-06` Убрать standalone escalation по сложности и review exhaustion из + применимых Bug Fix и Feature flow contracts. +- `REQ-07` Требовать scoped и current approval evidence, связанное с тем + конкретным execution gate, для которого нужно разрешение. +- `REQ-08` Разрешить обычное non-risky изменение кода и подготовку PR без + Human Gate на сам edit step; PR review, rollback и stop conditions остаются + контролями delivery. + +## Non-Scope + +- `NS-01` Изменение runtime-кода, production configuration, release path или + deployment behavior. +- `NS-02` Неявное разрешение merge, release, deployment, external messaging, + publication, live-data mutation или других external writes. +- `NS-03` Обязательное применение FPF или другой внешней reasoning methodology; + Structured Decision Protocol должен оставаться self-contained. +- `NS-04` Создание отдельного ADR для feature-local governance contract. +- `NS-05` Изменение human-only prompt catalog: prompt files не входят в scope + governed implementation этой feature. + +## Constraints / Assumptions + +- `ASM-01` Issue #117 и её acceptance criteria являются task-level source для + delivery intent; canonical ownership после реализации принадлежит + `engineering/autonomy-boundaries.md` и соответствующим flow documents. +- `CON-01` Existing project policies, compliance rules, contracts и explicit + approvals остаются stronger constraints и не могут быть отменены protocol. +- `CON-02` P0 остаётся read-only и не выполняет implementation discovery, + experiments, file changes или external writes. +- `CON-03` Решение является одной documentation delivery-unit; runtime C4 и + production rollout не применимы. +- `CON-04` Отдельное product/business value judgment не требуется, если + canonical task уже задаёт intent и acceptance; missing value priority + остаётся `escalate`. +- `CON-05` FPF или другая reasoning methodology могут использоваться как + опциональный supporting analysis, но их отсутствие не блокирует protocol и + не создаёт Human Gate. +- `CON-06` Core documentation candidate появился в commits `9822d88`–`d3639b1` + до bootstrap этого feature package. Recovery review может принять или + отклонить этот existing candidate, но не должен изображать, что исторические + writes прошли Plan Ready задним числом. + +## Design Requirement Decision + +| Decision | Reason | Downstream owner | +| --- | --- | --- | +| `Design required: yes` | Feature вводит новый cross-flow decision protocol и меняет authority, carrier, routing и approval contracts | [`design.md`](design.md) | + +## Artifact Routing Decision + +| Artifact | Decision | Trigger / reason | Route / owner | +| --- | --- | --- | --- | +| `use-cases/README.md` | omitted | Нет нового устойчивого user/operator journey; acceptance scenarios полностью покрываются в brief | `none` | +| `runtime-surfaces.md` | omitted | Нет runtime surface или implementation inventory, который нужно проецировать | `none` | +| `contracts/.md` | omitted | Нет API/event/queue/file/runtime-config connector; governance contract остаётся в design | `none` | +| `diagrams/-sequence.md` | omitted | Lifecycle описывается в flow prose и таблицах, отдельная temporal review boundary не нужна | `none` | +| ADR | omitted | Решение feature-local и не меняет reusable architecture boundary | `none` | + +## Validation Profile Decision + +| Profile | Triggers / rationale | Downgrade approval | +| --- | --- | --- | +| `documentation` | Меняются только governed Markdown и priming YAML; executable behavior, production config, contracts и release paths не меняются | `none` | + +## Verify + +### Acceptance scenarios + +- `SC-01` При нескольких допустимых local approaches агент отбрасывает + нарушающие constraints, фиксирует rationale и продолжает без эскалации + только из-за близости вариантов. +- `SC-02` При unknown, требующем experiment/discovery/mutation до выбора + delivery route, задача передаётся в Research Flow без mutation state и с + явными вопросом, budget и stopping condition. +- `SC-03` После Research probe evidence и limitations записываются, затем + повторяются Structured Decision Protocol и Task Routing до delivery. +- `SC-04` При missing product/value judgment protocol возвращает `escalate` с + точным вопросом, а не выбирает priority молча. +- `SC-05` При unauthorized external/production action подготовка и validation + продолжаются, но exact execution gate остаётся заблокирован. +- `SC-06` Scoped current preauthorization принимается только для названного + action, target/environment, scope и limits. +- `SC-07` Исчерпание review budget останавливает неизменённый loop и вызывает + replan, bounded probe или `escalate`, но не создаёт Human Gate само по себе. +- `SC-08` Implementation-only unknown для уже выбранного delivery route + откладывается в P1/P2 grounding, а не меняет P0 route на Research. +- `SC-09` При заданных intent и scope агент может автономно внести обычное + non-risky изменение кода и подготовить PR; Human Gate не возникает на edit + step, а review, rollback и stop conditions остаются обязательными. +- `SC-10` Агент автономно готовит analysis, design, validation и rollback для + security/compliance change, но не вносит material boundary mutation без + specific authority; наличие такой authority не разрешает последующее + risk-bearing production/live execution. + +### Negative cases + +- `NEG-01` Broad, inferred, stale или overridden permission не считается + approval evidence. +- `NEG-02` `Execution approval` не меняет protocol outcome и не расширяет + authority за пределы exact gate. +- `NEG-03` Tie-breakers не могут выбрать отсутствующий business priority и не + могут отменить hard constraint, policy или compliance requirement. + +### Checks and evidence + +| Check ID | Check | Expected evidence | +| --- | --- | --- | +| `CHK-01` | `ruby tools/validate-priming-manifests.rb template/memory-bank` | Все priming manifests schema-valid и paths resolvable | +| `CHK-02` | `memory-bank-cli lint --scope-root template/memory-bank --entrypoint template/memory-bank/README.md`; `memory-bank-cli lint --scope-root memory-bank --entrypoint memory-bank/README.md` | Generic template и project-level package не содержат broken links, orphan docs или unreachable docs | +| `CHK-03` | `memory-bank-cli doctor --profile template` | Нет doctor errors/warnings | +| `CHK-04` | `git diff --check` | Нет whitespace errors или conflict markers | +| `CHK-05` | Semantic review of autonomy, routing, validation, Bug Fix and Feature docs | All `REQ-*`, `SC-*` and `NEG-*` have canonical owner/evidence path | + +### Evidence contract + +`EVID-01` — текущий issue #117 и её comments/acceptance criteria. + +`EVID-02` — canonical [autonomy boundaries](../../../template/memory-bank/engineering/autonomy-boundaries.md) +с protocol schema, outcome semantics, carrier rules и approval evidence. + +`EVID-03` — [Task Routing](../../../template/memory-bank/flows/routing.md), [Research Flow](../../../template/memory-bank/flows/research.md), +Bug Fix и Feature flow с P0, Research handoff, review convergence и Human +Routing rules. + +`EVID-04` — validation profile contract с exact execution approval gate. + +`EVID-05` — outputs `CHK-01`–`CHK-04` и semantic review record этого package. + +`EVID-06` — отдельные non-authoring Plan Ready и implementation review records, +которые называют frozen revisions, findings, dispositions и verdicts. + +## Traceability + +| Requirement | Acceptance / evidence | +| --- | --- | +| `REQ-01`, `REQ-02`, `REQ-03`, `REQ-07` | `SC-01`, `SC-04`, `SC-05`, `SC-06`, `NEG-01`–`NEG-03`, `EVID-02`, `EVID-04` | +| `REQ-04` | `SC-02`, `SC-03`, `SC-08`, `EVID-03` | +| `REQ-05`, `REQ-06` | `SC-04`, `SC-05`, `SC-07`, `SC-10`, `EVID-02`–`EVID-04` | +| `REQ-08` | `SC-09`, `SC-10`, `EVID-02`–`EVID-04` | +| `REQ-01`–`REQ-08` | `CHK-01`–`CHK-05`, `EVID-05`, `EVID-06` | diff --git a/memory-bank/features/FT-117/design.md b/memory-bank/features/FT-117/design.md new file mode 100644 index 0000000..4c5cc62 --- /dev/null +++ b/memory-bank/features/FT-117/design.md @@ -0,0 +1,177 @@ +--- +title: "FT-117: Structured Decision Protocol Design" +doc_kind: feature +doc_function: canonical +purpose: "Selected solution и design-pack manifest для FT-117. Определяет ownership и cross-flow contract, не заменяя canonical autonomy и flow documents." +derived_from: + - brief.md + - ../../../template/memory-bank/engineering/autonomy-boundaries.md + - ../../../template/memory-bank/engineering/validation-profiles.md + - ../../../template/memory-bank/flows/routing.md + - ../../../template/memory-bank/flows/research.md + - ../../../template/memory-bank/flows/bug-fix.md + - ../../../template/memory-bank/flows/feature.md +status: active +audience: humans_and_agents +must_not_define: + - ft_117_problem_space + - ft_117_acceptance_criteria + - implementation_sequence +--- + +# FT-117: Structured Decision Protocol Design + +## Solution Summary + +`SOL-01` — `engineering/autonomy-boundaries.md` остаётся canonical owner +Structured Decision Protocol, carrier selection, execution authorization и +approval evidence. Protocol является self-contained; FPF или другая reasoning +methodology могут дать supporting analysis, но не являются dependency. + +`SOL-02` — `flows/routing.md` реализует read-only P0, Research handoff и Human +Routing только после protocol outcome `escalate`. + +`SOL-03` — `flows/bug-fix.md` и `flows/feature.md` используют protocol для +неопределённости и review exhaustion; complexity, ambiguity и exhausted budget +не являются самостоятельными Human Gates. + +`SOL-04` — `engineering/validation-profiles.md` отделяет autonomous design, +rehearsal, validation и rollback preparation от exact approval-gated execution +step. + +`SOL-05` — `flows/research.md` владеет probe lifecycle после P0 handoff и +возвратом evidence в повторный Structured Decision Protocol и Task Routing. + +`SOL-06` — ordinary non-risky code edit остаётся autonomous work, а PR review, +rollback и stop conditions остаются assurance controls без Human Gate на edit +step. Analysis, design и validation security/compliance change также автономны, +но material boundary mutation требует specific task/policy authority и не +разрешает последующий risk-bearing production/live execution. + +## Design Decisions + +### Solution Traceability + +| Requirement refs | Selected solution refs | +| --- | --- | +| `REQ-01`, `REQ-02`, `REQ-07` | `SOL-01`, `SD-01`, `SD-04` | +| `REQ-03` | `SOL-01`, `SD-02` | +| `REQ-04` | `SOL-02`, `SOL-05`, `SD-03` | +| `REQ-05`, `REQ-06` | `SOL-03`, `SOL-04`, `SOL-06` | +| `REQ-08` | `SOL-06` | + +### `SD-01` — Four-role decision record + +Каждая non-trivial record различает authority source, accountable decision owner, +canonical carrier и execution approver/approval evidence. +Это предотвращает +смешение rationale с permission и позволяет сохранять decision autonomy при +заблокированном external execution. + +### `SD-02` — Hard constraints before tie-breakers + +Сначала исключаются options, нарушающие intent, invariants, contracts, policy, +compliance или authority. Затем применяются tie-breakers в фиксированном порядке: +existing canonical pattern, smallest reversible change, smallest blast radius, +lowest operational/maintenance complexity, strongest available verification. +Tie-breakers не выбирают отсутствующий business value priority. + +### `SD-03` — Probe belongs to Research before delivery + +P0 только классифицирует route. Если unknown требует experiment, implementation +discovery, broad evidence collection или mutation до выбора delivery route, он +передаётся Research Flow с budget и stopping condition. После probe protocol и +routing повторяются. + +### `SD-04` — Approval checked at exact gate + +Decision outcome не является execution permission. Approval evidence должна быть +specific, current, scoped, owned и привязана к exact execution gate; broad или +inferred permission отклоняется. + +## Design Pack + +| Artifact | Relation | Direct canonical ownership | Readiness / source | +| --- | --- | --- | --- | +| `design.md` | `root` | Feature-local selected solution and `SD-01`–`SD-04`; default owner for `SOL-01`–`SOL-06` | `active`; pack root | +| `engineering/autonomy-boundaries.md` | `external-dependency` | Protocol, carrier, authorization и approval-evidence semantics | `active`; canonical owner | +| `flows/routing.md` | `external-dependency` | P0, Research handoff и Human Routing semantics | `active`; canonical flow owner | +| `flows/research.md` | `external-dependency` | Probe lifecycle, evidence handoff и repeat-routing semantics | `active`; canonical flow owner | +| `flows/bug-fix.md` | `external-dependency` | Bug Fix reroute/replan semantics | `active`; canonical flow owner | +| `flows/feature.md` | `external-dependency` | Feature ambiguity/review-convergence semantics | `active`; canonical flow owner | +| `flows/epic.md` | `external-dependency` | Epic-local carrier selection and decision-log rules | `active`; canonical flow owner | +| `flows/templates/epic/decision-log.md` | `external-dependency` | Instantiated epic decision carrier terminology | `active`; canonical template owner | +| `engineering/validation-profiles.md` | `external-dependency` | Validation and execution-approval separation | `active`; canonical profile owner | + +Indexes, priming manifests, the project feature index and `memory-bank/.lock` +are synchronized projections or repository metadata, not additional design-pack +owners. Their realization and checks are mapped in `implementation-plan.md`. + +## C4 Applicability Decision + +`C4-00: not required` — change surface состоит из governed documentation и +priming manifests. Он не вводит или не меняет deployable/runtime/container, +queue, storage, network, security runtime boundary или production topology. +Cross-document ownership отображена в Design Pack и не требует C4 runtime view. + +## 4+1 Viewpoint Coverage + +| View | Status | Coverage / source | +| --- | --- | --- | +| Logical | `covered` | `REQ-*`, `SC-*` и ownership split из `brief.md` / `SD-01` | +| Process | `covered` | P0 → Research → repeat routing и exact execution gate из `SD-03`/`SD-04` | +| Development | `covered` | Canonical owners: autonomy, routing, flow и validation docs | +| Physical | `N/A` | Нет runtime/deployable или deployment topology change; `C4-00` | +| Scenarios (+1) | `covered` | `SC-01`–`SC-10` и `NEG-01`–`NEG-03` | + +## Architecture Coverage Decision + +| Concern | Decision | Evidence | +| --- | --- | --- | +| Components / ownership | `covered` | `SOL-01`–`SOL-06`, Design Pack | +| Connectors / bindings | `covered` as document references | Cross-flow Markdown dependencies and priming inputs; no runtime connector | +| Configuration / contracts | `covered` | Protocol schema and approval evidence contract | +| Behavioral semantics | `covered` | Outcome semantics, P0 and Human Gate rules | +| Quality / evolution | `covered` | Reversibility, blast radius, review convergence and rollback preparation | + +## Cross-View Correspondence + +| Scenario | Logical ref | Process ref | Development ref | Physical ref | Checks / evidence | +| --- | --- | --- | --- | --- | --- | +| `SC-01` | `REQ-03`, `SD-02` | Protocol option selection | `autonomy-boundaries.md` | `N/A`: no runtime topology | `CHK-05`, `EVID-02` | +| `SC-02` | `REQ-04` | P0 → Research handoff | `routing.md`, `research.md` | `N/A`: pre-delivery read-only routing | `CHK-05`, `EVID-03` | +| `SC-03` | `REQ-04` | Probe → evidence → repeat protocol/routing | `research.md`, `routing.md` | `N/A`: no runtime topology | `CHK-05`, `EVID-03` | +| `SC-04` | `REQ-05` | Escalation with exact question | `autonomy-boundaries.md` | `N/A`: no runtime topology | `CHK-05`, `EVID-02` | +| `SC-05` | `REQ-05`, `REQ-07` | Preparation → exact gated execution | `autonomy-boundaries.md`, `validation-profiles.md` | `N/A`: no runtime topology | `CHK-05`, `EVID-04` | +| `SC-06` | `REQ-07` | Scoped authorization at execution gate | `validation-profiles.md` | `N/A`: no runtime topology | `CHK-05`, `EVID-04` | +| `SC-07` | `REQ-06` | Review exhaustion → replan/probe/escalate | `feature.md`, `autonomy-boundaries.md` | `N/A`: no runtime topology | `CHK-05`, `EVID-03` | +| `SC-08` | `REQ-04` | Established delivery route → P1/P2 grounding | `routing.md`, `feature.md` | `N/A`: no runtime topology | `CHK-05`, `EVID-03` | +| `SC-09` | `REQ-08` | Edit → PR review → rollback/stop controls | `autonomy-boundaries.md`, `validation-profiles.md` | `N/A`: runtime implementation is out of this documentation feature | `CHK-05`, `EVID-03`, `EVID-04` | +| `SC-10` | `REQ-05`, `REQ-08` | Preparation → repository authority gate → separate live execution gate | `autonomy-boundaries.md`, `validation-profiles.md` | `N/A`: governance contract only | `CHK-05`, `EVID-02`, `EVID-04` | + +## Design Verification + +| Analysis | Required | Method | Result / evidence | +| --- | --- | --- | --- | +| Decision authority vs execution permission | `yes` | Semantic review of `SD-01` and `SD-04` | Fields and exact gate are explicit in canonical owner | +| P0 / Research routing | `yes` | Review routing predicates and priming manifest | P0 read-only; probe handoff is explicit | +| Research lifecycle handoff | `yes` | Review `research.md` boundary and repeat-routing contract | Probe owns question/budget/evidence and cannot silently commit delivery | +| Review exhaustion | `yes` | Review Bug Fix/Feature gate text | Replan/probe/escalate replaces exhaustion-only gate | +| Ordinary code edit vs PR review | `yes` | Review autonomy and validation contracts | Edit is not a Human Gate; PR review and rollback remain controls | +| Contract compatibility | `no` | No runtime/API contract changes | No API, event, schema or file-format surface | +| State/transition completeness | `yes` | Review protocol outcomes and Research handoff states | `proceed`, `bounded_probe`, `escalate` and repeat routing are explicit | +| Failure propagation | `yes` | Review stop/escalation semantics | Unbounded risk leads to exact escalation or stop | +| Concurrency/ordering | `no` | No runtime execution ordering introduced | No concurrent runtime path in scope | +| Security boundaries | `yes` | Review approval and security-sensitive Human Gate rules | Security/live-state boundary remains explicit | +| Capacity/latency | `no` | No runtime performance target | Documentation-only change | +| Migration/evolution safety | `yes` | Review carrier ownership, rollback and review convergence | Canonical owner and revision handoff are explicit | +| C4 runtime model | `no` | Applicability check | `C4-00`; no runtime boundary | +| UI / interaction contract | `no` | Trigger check | No UI/API/event/file/runtime-config change | + +## Solution Ready + +- `SOL-01`–`SOL-06` have a direct canonical owner. +- `SD-01`–`SD-04` are feature-local rationale; reusable semantics remain in + their external canonical owners. +- `C4-00` and 4+1 coverage are recorded. +- No optional artifact is required for Solution Ready. diff --git a/memory-bank/features/FT-117/feature-review-report.md b/memory-bank/features/FT-117/feature-review-report.md new file mode 100644 index 0000000..997e529 --- /dev/null +++ b/memory-bank/features/FT-117/feature-review-report.md @@ -0,0 +1,240 @@ +--- +title: "FT-117: Feature Review Report" +doc_kind: feature-support +doc_function: reference +purpose: "Semantic self-review и validation evidence для FT-117; не владеет requirements, selected solution или execution plan." +derived_from: + - brief.md + - design.md + - implementation-plan.md +status: active +audience: humans_and_agents +review_mode: self_review +--- + +# FT-117: Feature Review Report + +## Review scope + +- Reviewed package: `FT-117` (`brief.md`, `design.md`, `implementation-plan.md`). +- Reviewed canonical owners: `engineering/autonomy-boundaries.md`, + `engineering/validation-profiles.md`, `flows/routing.md`, + `flows/research.md`, `flows/bug-fix.md`, `flows/feature.md` and `flows/epic.md`. +- Reviewed affected support/index/priming surfaces: `engineering/README.md`, + `flows/README.md`, `flows/templates/epic/decision-log.md`, + `flows/priming/{research,bug-fix,feature}.yaml`, `memory-bank/features/README.md` + and `memory-bank/.lock`. +- Explicit audit exclusion: `template/memory-bank/prompts/**` is human-only and + unchanged; no prompt artifact was inspected or used. +- Reviewed repository baseline: immutable commit `d3639b1`. +- Candidate revision manifest is recorded below for the current package and all + changed external owners; hashes are recomputed after the final document edit + and are the input to independent Plan Ready review. +- Review mode: `self_review` — no separate non-authoring reviewer was available + in this execution context. + +## Findings + +| Finding ID | Requirement | Evidence | Disposition | +| --- | --- | --- | --- | +| `F-01` | Protocol owns authority, carrier, execution authorization and approval evidence | `autonomy-boundaries.md` frontmatter, role contract, full record shape and valid approval evidence section | `closed` | +| `F-02` | Hard constraints precede stable tie-breakers | Structured Decision Protocol order and `SD-02` | `closed` | +| `F-03` | P0 remains read-only and probes route through Research | Routing/research contracts, priming manifest and `SC-02`, `SC-03`, `SC-08` | `closed` | +| `F-04` | Bug Fix/Feature review exhaustion does not create a gate by itself | Flow contracts and `SC-07` | `closed` | +| `F-05` | Package is reachable and structurally valid | `CHK-01`–`CHK-04` outputs below | `closed` | +| `F-06` | Protocol remains self-contained without mandatory FPF dependency | `autonomy-boundaries.md`, `design.md` and `CON-05` | `closed` | +| `F-07` | Security/compliance preparation, repository authority and live execution are distinct gates | `autonomy-boundaries.md`, `validation-profiles.md`, `SC-10` | `closed` | +| `F-08` | Research receives the canonical protocol before bootstrap | `research.md` dependency and `priming/research.yaml` | `closed` | +| `F-09` | Audit scope covers every governed path in the candidate diff | Review scope above and Candidate Revision Manifest | `closed` | + +## Acceptance coverage + +| Scenario group | Covered by | Result | +| --- | --- | --- | +| Autonomous option selection and missing value judgment | `SC-01`, `SC-04`, `NEG-03` | pass | +| P0, Research and repeat routing | `SC-02`, `SC-03`, `SC-08` | pass | +| Exact execution approval and scoped authorization | `SC-05`, `SC-06`, `NEG-01`, `NEG-02` | pass | +| Review exhaustion and flow convergence | `SC-07` | pass | +| Ordinary code edit and PR review boundary | `SC-09` | pass | +| Security/compliance repository and live-execution boundaries | `SC-10` | pass | +| Documentation integrity | `CHK-01`–`CHK-04` | pass | + +## Deterministic checks + +| Check | Result | +| --- | --- | +| `ruby tools/validate-priming-manifests.rb template/memory-bank` | pass: 16 manifests validated | +| `memory-bank-cli lint --scope-root template/memory-bank --entrypoint template/memory-bank/README.md` | pass: links, frontmatter dependencies, reachability and index compliance | +| `memory-bank-cli lint --scope-root memory-bank --entrypoint memory-bank/README.md` | pass: project package links, frontmatter dependencies, reachability and index compliance | +| `memory-bank-cli doctor --profile template` | pass: 0 errors, 0 warnings | +| `git diff --check` | pass | + +## Candidate Revision Manifest + +| Candidate | Revision evidence | +| --- | --- | +| Repository baseline | commit `d3639b1` | +| `FT-117/README.md` | `194f180d9d7c6400824ce4ac69082e4282de477242ccebf3e210b04031ec5f18` | +| `brief.md` | `9e0f7a76cb9bbca49306c7e65944bb1e68eb7f8df2cc0b049e2a80b5b7817b4d` | +| `design.md` | `0dd7ae943707ea9a7aac8f59a39c100103d9ed2f7d2def189dfb73a17ee60e8a` | +| `implementation-plan.md` | `3399ce26a03b133006463b31b8c29854124b17c6f73ba564a4cc964d43784fd6` | +| `engineering/README.md` | `50f1efb6ff9c68cd72eb22949ef778ffaf0fef9dc8d00847016aab0f4aad63aa` | +| `engineering/autonomy-boundaries.md` | `0bc9446a2e28230a77a2d173af00fc4776e6dcf66bf68cf5164c2bea95c0643b` | +| `engineering/validation-profiles.md` | `bf4b7ea1c4e82c9e15749a1fb6f7fdd1beb60b38185a040eb9610f6ec81f1ec9` | +| `flows/README.md` | `e1874780be91df99d7fa90f2680320ed7f30c9dea120be7741304ccfe25b94ea` | +| `flows/bug-fix.md` | `c748d08faefe2fcacfacf13964f199ac1bca10ac3432859d90510dd8caa517a3` | +| `flows/epic.md` | `13a7a7a81437969d4193c8c716e29e49340d66d44afa775114254c3d7ed619f0` | +| `flows/feature.md` | `d267ce1f251b8b58c703bf4e8bc805445ebdc01886bd43ec5facde48e9aeddc6` | +| `flows/routing.md` | `9cc785e2880ed0d6329d89bd6748addc8e68071db756653c3d007ec7b1a0643c` | +| `flows/research.md` | `a8debef19df9b9a49f340f16bb97d78ed07399d71c4e24dd115696de5ae02036` | +| `flows/templates/epic/decision-log.md` | `29619853753af94d0c1714019d9a4e6a226d2257f90f21a4b0e9d217be79dee4` | +| `flows/priming/bug-fix.yaml` | `cd6d7707fcc9cf231172ecf9188d1dc7f83793352b1baf6293b59954a427a36d` | +| `flows/priming/feature.yaml` | `0626e1c1b03a1c96d8c018389253777eca5c81af5e60906cdd13e7f3973f0656` | +| `flows/priming/research.yaml` | `6d72986736eb9f41f21e47e238b6b04f6d17eda3875c009bacb448d078dca543` | +| `memory-bank/features/README.md` | `9313704c26297aa50afa0a69665061182dda4945107ad9019764f4af5503ecc7` | +| `memory-bank/.lock` | `4290dcfa8a1453edccb70b6f0e5bac8a71570402139e18dea7b81be8adcd17db` | + +`feature-review-report.md` intentionally does not record its own digest: adding +that digest would mutate the reviewed file and invalidate the value recursively. + +## Limitations + +This is a documentation self-review, not an independent review and not a +runtime test. The package does not authorize merge, release, deployment, +publication or external task-tracker writes. A separate reviewer or PR review +may add findings; canonical owners must be updated before dependent documents. + +## Independent Plan Ready Review History + +### Attempt 1 — blocked + +- Reviewer: OpenAI Codex, independent non-authoring reviewer in an isolated + archive with repository artifacts treated read-only. +- Reviewed revision: `fbb3d851ca2a8a58910326e9687c56e9547d75f9`; + all 19 Candidate Revision Manifest digests matched the archive. +- Verdict: `BLOCKED_PLAN_READY`. +- Critical `C-01`: the earlier plan was retrospective and could not claim that + Plan Ready preceded commits `9822d88`–`d3639b1`. +- Important `I-01`: Epic/carrier and index surfaces were absent from the design + and realization maps. +- Important `I-02`: the isolated archive could not independently inspect the + grounded Git objects or baseline diff. +- Important `I-03`: `CHK-05` and required CI were not reproducible exact checks. +- Important `I-04`: after corrections, both the resulting draft and promoted + active plan revisions require independent clean review. +- Minor `M-01`: one summary omitted `SC-10`. +- Minor `M-02`: the Environment Contract miscounted verification commands. + +Disposition: all findings are addressed in the next candidate by the recovery +boundary, complete change-surface mapping, exact Git/check/CI receipts and the +required two-stage Plan Ready review. Historical sequencing remains disclosed. + +### Attempt 2 — blocked + +- Reviewer: OpenAI Codex, independent non-authoring reviewer in an isolated Git + clone; no repository or external writes were performed. +- Reviewed base: `fbb3d851ca2a8a58910326e9687c56e9547d75f9`, plus the frozen + five-file recovery candidate recorded in the manifest below. +- Verdict: `BLOCKED_PLAN_READY`. +- Important `R2-I-01`: one exact Research assertion did not span a Markdown + line break, and the pre-commit diff check omitted working-tree corrections. +- Important `R2-I-02`: the current request did not specifically name permission + to push branch `docs/issue-117-autonomy-fpf` or update PR #118. +- Important `R2-I-03`: terminal metadata changes lacked their own commit, push, + CI and final convergence step. +- Minor `R2-M-01`: `STEP-01` omitted `FT-117/README.md` from its touchpoints. + +Disposition: the next candidate uses a multiline assertion, checks committed +and working-tree diffs separately, keeps branch/PR push behind explicit +`AG-01`, includes the package README and adds terminal commit/push/CI/convergence. + +### Attempt 3 — clean draft verdict + +- Reviewer: OpenAI Codex, independent non-authoring reviewer in an isolated Git + clone; repository and external state remained unchanged. +- Reviewed base: `fbb3d851ca2a8a58910326e9687c56e9547d75f9`. +- Frozen package hashes: `README 194f180…`, `brief 955ad5e…`, `design 0dd7ae9…`, + `plan 7a2e753…`, `report 5f82197…`; all identities matched. +- Verdict: `CLEAN_PLAN_READY` for the draft revision. +- `R2-I-01`, `R2-I-02`, `R2-I-03` and `R2-M-01`: `closed`. +- Exact local checks, semantic scenarios and zero template leakage passed. +- Remaining gate: promote the plan to `active`, freeze it and obtain a clean + independent re-review of that active revision. + +### Attempt 4 — blocked active verdict + +- Reviewer: OpenAI Codex, independent non-authoring reviewer in an isolated Git + clone; all frozen hashes and checks matched. +- Verdict: `BLOCKED_PLAN_READY`. +- Important `I-01`: the historical self-review verdict below still used the + present-tense phrase “remains `status: draft`” after plan promotion. + +Disposition: retain the self-review limitation but describe it as the state at +the time of that review; freeze and re-review the unchanged active plan with the +synchronized evidence carrier. + +### Attempt 5 — clean active verdict + +- Reviewer: OpenAI Codex, independent non-authoring reviewer in an isolated Git + clone; no repository or external writes were performed. +- Frozen active plan: + `5cc90fda452aed260d462d2e5cc942242f5e9eb6e8da9ec4a87e2d3155678dec`. +- Evidence carrier reviewed at: + `4cf6a9fbff889a2c64850777d52495f01c44742e060188f0cea4e0025bd964be`. +- Open critical/important findings: `none`. +- Verdict: `CLEAN_PLAN_READY`. + +Plan Ready was closed for local `STEP-01`–`STEP-03`; branch push, PR update and +CI were still blocked by pending `AG-01` at the time of Attempt 5. + +### Attempt 6 — clean approval-evidence revision + +- Reviewer: OpenAI Codex, independent non-authoring reviewer in an isolated Git + clone; no repository or external writes were performed. +- Frozen active plan: + `9920295dec22feefa2531b7f50c6e1109a815c4da760d179bd9676a8102983cb`. +- Open critical/important findings: `none`. +- Verdict: `CLEAN_PLAN_READY`. +- The only plan delta from the prior clean revision is current scoped commit/push + authority in `AG-01`; merge, release, deploy and publication remain excluded. + +## Execution Evidence + +- Recovery correction commit: `f7667514bb39b47deab023c717892e5c63ad94e7`. +- Main synchronization commit: `c2a0578`; the only manual conflict resolution + preserved both `FT-113` and `FT-117` entries in `memory-bank/features/README.md`. +- Required GitHub check `CI / validate-template`: `success` on `c2a0578`, run + [31751810935](https://github.com/dapi/memory-bank/actions/runs/31751810935). +- Recovery evidence refresh head: `1f00e35b2a12973b24eab4a5057b8b52dc4fd81b`; + exact-head `CI / validate-template`: `success`, run + [31751884082](https://github.com/dapi/memory-bank/actions/runs/31751884082). +- Post-merge local manifest tests/validator, both lints, doctor and diff check: + `pass`. +- Candidate manifest hashes were refreshed after merging current `origin/main`; + upstream BDD/FT-113 changes remain owned by main and are not FT-117 scope. + +## Independent Implementation Review + +- Reviewer: OpenAI Codex, independent non-authoring read-only reviewer. +- Delivered head: `1f00e35b2a12973b24eab4a5057b8b52dc4fd81b`. +- Current main: `079b79d139fa91fec0ec8a65fcbc6f387c684ee5`. +- Implementation baseline: `daa7cb639d2bc2741da8b829a125546b45bf8a0e`. +- Critical findings: `none`. +- Important findings: `none`. +- Minor `M-01`: report referenced the preceding successful CI run instead of + exact-head run `31751884082`; closed by the Execution Evidence update above. +- Requirements `REQ-01`–`REQ-08`, scenarios `SC-01`–`SC-10`, negative cases, + ownership, cross-flow consistency, BDD/FT-113 compatibility, simplify review + and scope boundaries: `pass`. +- Verdict: `CLEAN_IMPLEMENTATION_REVIEW`. + +This verdict does not authorize merge, release, deployment or publication. The +terminal metadata revision still requires its own successful CI and final +convergence read. + +## Self-review Verdict + +`implementation_candidate_complete` — at the time of this self-review all +issue-level corrections were reflected in the package and deterministic checks +passed. This self-review did not provide the independent Plan Ready verdict; +the then-draft plan required the separate review history recorded above. diff --git a/memory-bank/features/FT-117/implementation-plan.md b/memory-bank/features/FT-117/implementation-plan.md new file mode 100644 index 0000000..da67baa --- /dev/null +++ b/memory-bank/features/FT-117/implementation-plan.md @@ -0,0 +1,183 @@ +--- +title: "FT-117: Recovery Acceptance Plan" +doc_kind: feature +doc_function: derived +purpose: "Forward recovery plan for independently reviewing, accepting and closing the pre-existing FT-117 documentation candidate without claiming retroactive Plan Ready compliance." +derived_from: + - brief.md + - design.md +status: archived +audience: humans_and_agents +must_not_define: + - ft_117_scope + - ft_117_selected_design + - ft_117_acceptance_criteria + - ft_117_validation_profile +--- + +# FT-117: Recovery Acceptance Plan + +## Цель текущего плана + +Провести от текущего frozen candidate вперёд воспроизводимую recovery-приёмку +issue #117: закрыть traceability gaps, получить независимые Plan Ready и +implementation verdicts, выполнить exact local/CI checks и только после этого +закрыть lifecycle package. + +Core changes в commits `9822d88`–`d3639b1` являются existing adoption input. +Этот план не утверждает, что исторические writes прошли Plan Ready до execution. +Он разрешает только review, bounded corrections, validation и acceptance +existing candidate; новый semantic scope требует нового routing. + +## Grounding Evidence + +- Pre-change issue baseline: `daa7cb639d2bc2741da8b829a125546b45bf8a0e`. +- Core implementation candidate: `d3639b118a48f3215567a26a3b6d430cc2b4d6f6`. +- Recovery-plan starting revision: `fbb3d851ca2a8a58910326e9687c56e9547d75f9`. +- Grounded at: `2026-08-14`. + +| Grounding ID | Exact command / path | Observed fact | Plan impact | +| --- | --- | --- | --- | +| `GRND-01` | `git cat-file -e daa7cb639d2bc2741da8b829a125546b45bf8a0e^{commit}`; `git cat-file -e d3639b118a48f3215567a26a3b6d430cc2b4d6f6^{commit}`; `git cat-file -e fbb3d851ca2a8a58910326e9687c56e9547d75f9^{commit}` | Baseline, core candidate and recovery start are immutable repository objects | `STEP-01` re-verifies the exact objects before acceptance | +| `GRND-02` | `git diff --name-status daa7cb639d2bc2741da8b829a125546b45bf8a0e..d3639b118a48f3215567a26a3b6d430cc2b4d6f6` | Core candidate changes nine autonomy/routing/flow/carrier documents | All nine surfaces are mapped below | +| `GRND-03` | `git diff --name-status d3639b118a48f3215567a26a3b6d430cc2b4d6f6..fbb3d851ca2a8a58910326e9687c56e9547d75f9` | Recovery start adds the project package, Research handoff, three priming inputs and validation refinements | Package, projections and metadata are explicit execution surfaces | +| `GRND-04` | `.github/workflows/ci.yml`, job `validate-template` | Required CI runs manifest tests/validator, both lints, doctor and downstream-init smoke test | `STEP-04` requires exact `CI / validate-template` success | +| `GRND-05` | `template/memory-bank/engineering/autonomy-boundaries.md`; `template/memory-bank/flows/{routing,research,bug-fix,feature,epic}.md`; `template/memory-bank/engineering/validation-profiles.md` | Canonical owners contain the candidate protocol and cross-flow behavior | `STEP-02` executes exact structural assertions and semantic review | +| `GRND-06` | `memory-bank/features/README.md`; `memory-bank/.lock` | FT-117 belongs to project-local history; the feature index is adapted metadata rather than generic payload | `STEP-03` verifies placement and zero template leakage | + +## Historical Boundary And Recovery Disposition + +The first independent review recorded `BLOCKED_PLAN_READY` because the previous +plan described already-delivered work as future execution. This revision adopts +the reviewer disposition: it treats `daa7cb6..fbb3d85` as immutable input and +defines only prospective recovery acceptance. Historical noncompliance remains +visible in the review record and is not erased by later clean verdicts. + +## Implementation Priming + +| Order | Exact path / symbol | Grounding refs | Purpose | Required before | +| --- | --- | --- | --- | --- | +| `1` | `memory-bank/features/FT-117/brief.md#constraints--assumptions` | `GRND-01`–`GRND-03` | Confirm recovery boundary and unchanged issue scope | `STEP-01` | +| `2` | `memory-bank/features/FT-117/design.md#design-pack` | `GRND-02`, `GRND-03` | Confirm every canonical changed owner and projection classification | `STEP-01` | +| `3` | `template/memory-bank/engineering/autonomy-boundaries.md#structured-decision-protocol` | `GRND-05` | Verify roles, outcomes, tie-breakers and approval separation | `STEP-02` | +| `4` | `template/memory-bank/flows/routing.md#human-routing` | `GRND-05` | Verify P0-safe decision and exact Human Routing conditions | `STEP-02` | +| `5` | `template/memory-bank/flows/research.md#boundary-rules` | `GRND-03`, `GRND-05` | Verify probe handoff and repeat-routing semantics | `STEP-02` | +| `6` | `template/memory-bank/flows/bug-fix.md#entry-gate`; `template/memory-bank/flows/feature.md#upstream-ready--plan-ready` | `GRND-05` | Verify expected-behavior routing and review convergence | `STEP-02` | +| `7` | `template/memory-bank/engineering/validation-profiles.md#escalation-and-downgrade-rules` | `GRND-05` | Verify exact execution approval gate | `STEP-02` | +| `8` | `.github/workflows/ci.yml#L12`; job `validate-template` | `GRND-04` | Confirm required CI name and commands | `STEP-04` | + +If any named path, heading, commit object or CI job is absent, stop for +re-grounding before execution. + +## Test Strategy + +| Surface | Refs | Exact local command / procedure | Required CI | Pass criterion | +| --- | --- | --- | --- | --- | +| Priming schema | `CHK-01` | `ruby tools/validate-priming-manifests-test.rb && ruby tools/validate-priming-manifests.rb template/memory-bank` | `CI / validate-template` | Tests pass and exactly 16 manifests validate | +| Links and reachability | `CHK-02` | `memory-bank-cli lint --scope-root template/memory-bank --entrypoint template/memory-bank/README.md && memory-bank-cli lint --scope-root memory-bank --entrypoint memory-bank/README.md` | `CI / validate-template` | Both commands return `Result: OK` | +| Template doctor | `CHK-03` | `memory-bank-cli doctor --profile template` | `CI / validate-template` | `0 error(s), 0 warning(s)` | +| Diff hygiene | `CHK-04` | `git diff --check daa7cb639d2bc2741da8b829a125546b45bf8a0e..HEAD && git diff --check` before commit; repeat the first command after commit | `CI / validate-template` | Committed range and frozen working-tree corrections both produce no output and exit zero | +| Protocol structure | `CHK-05` | Run the exact assertion block below, then independent semantic review of every `SC-*`/`NEG-*` | `CI / validate-template` plus independent review record | Every assertion returns at least one match; reviewer reports no open critical/important finding | +| Downstream install | `CHK-02`, `CHK-03` | Use the `Smoke-test downstream init` procedure from `.github/workflows/ci.yml` in CI | `CI / validate-template` | Job step succeeds | + +Exact `CHK-05` assertion block: + +```sh +rg -q 'authority source' template/memory-bank/engineering/autonomy-boundaries.md +rg -q 'decision owner' template/memory-bank/engineering/autonomy-boundaries.md +rg -q 'canonical carrier' template/memory-bank/engineering/autonomy-boundaries.md +rg -q 'execution approver / approval evidence' template/memory-bank/engineering/autonomy-boundaries.md +rg -q 'Outcome: proceed \| bounded_probe \| escalate' template/memory-bank/engineering/autonomy-boundaries.md +rg -q 'существующий canonical pattern; наименьшее обратимое изменение' template/memory-bank/engineering/autonomy-boundaries.md +rg -q 'P0 остаётся read-only' template/memory-bank/flows/routing.md +rg -U -q 'повторяет Structured Decision Protocol и Task\n[[:space:]]+Routing' template/memory-bank/flows/research.md +rg -q 'Human Gate нужен только при outcome' template/memory-bank/flows/feature.md +rg -q 'только при outcome `escalate`' template/memory-bank/flows/bug-fix.md +rg -q 'task/project-policy preauthorization may be approval evidence|task/project-policy preauthorization может быть approval evidence' template/memory-bank/engineering/validation-profiles.md +``` + +## Open Questions / Ambiguities + +`none` — historical sequencing is a disclosed lifecycle debt, not an unknown. +The recovery decision is whether the frozen existing candidate is acceptable; +it does not reconstruct or conceal its original execution order. + +## Environment Contract + +| Area | Contract | Used by | Failure symptom | +| --- | --- | --- | --- | +| setup | Repository clone/worktree contains Git objects through `HEAD`; `memory-bank-cli` is installed | `STEP-01`–`STEP-04` | Commit receipt or command unavailable | +| local validation | Run all six Test Strategy rows; do not substitute a generic docs read-through | `STEP-02`, `STEP-03` | Evidence cannot establish acceptance | +| CI | Existing PR #118 branch `docs/issue-117-autonomy-fpf`; required job `CI / validate-template` | `STEP-04` | Job absent, pending or non-success | +| authority | User approval `2026-08-14` explicitly authorizes commit and push for this work and says not to request commit/push permission again; target remains branch `docs/issue-117-autonomy-fpf` and PR #118 | `STEP-04`, `STEP-06` | Target/scope differs or authority is revoked | + +## Preconditions + +| ID | Required state | Used by | Blocks start | +| --- | --- | --- | --- | +| `PRE-01` | `brief.md` and `design.md` remain active; `brief.md` is `planned` | `STEP-01`–`STEP-03` | yes | +| `PRE-02` | This draft plan receives clean independent Plan Ready review, then the active revision receives clean re-review | `STEP-01`–`STEP-04` | yes | +| `PRE-03` | No semantic change beyond `REQ-01`–`REQ-08` entered the candidate | `STEP-02`, `STEP-03` | yes | + +## Design Realization Mapping + +| Refs | Direct owner / projection | Recovery target | Steps | Checks / evidence | +| --- | --- | --- | --- | --- | +| `SOL-01`, `SD-01`, `SD-02`, `SD-04` | `template/memory-bank/engineering/autonomy-boundaries.md` | Protocol, carrier and approval contract | `STEP-02` | `CHK-05`, `EVID-02`, `EVID-06` | +| `SOL-02`, `SD-03` | `template/memory-bank/flows/routing.md` | P0, Research and Human Routing | `STEP-02` | `CHK-05`, `EVID-03`, `EVID-06` | +| `SOL-05`, `SD-03` | `template/memory-bank/flows/research.md`; `flows/priming/research.yaml` projection | Probe lifecycle, bootstrap input and return | `STEP-02`, `STEP-03` | `CHK-01`, `CHK-05`, `EVID-03` | +| `SOL-03` | `template/memory-bank/flows/bug-fix.md`; `flows/feature.md`; `flows/priming/{bug-fix,feature}.yaml` projections | Reroute/replan semantics and required priming | `STEP-02`, `STEP-03` | `CHK-01`, `CHK-05`, `EVID-03` | +| `SOL-01`, `SD-01` | `template/memory-bank/flows/epic.md`; `flows/templates/epic/decision-log.md` | Epic carrier and template terminology | `STEP-02` | `CHK-02`, `CHK-05`, `EVID-02` | +| `SOL-04`, `SOL-06`, `SD-04` | `template/memory-bank/engineering/validation-profiles.md` | Approval timing and validation floor | `STEP-02` | `CHK-05`, `EVID-04`, `EVID-06` | +| `SOL-01`–`SOL-06` | `template/memory-bank/{engineering,flows}/README.md` projections | Navigation wording | `STEP-03` | `CHK-02` | +| `REQ-01`–`REQ-08` | `memory-bank/features/FT-117/*`, `memory-bank/features/README.md`, `memory-bank/.lock` | Project-local traceability, reachability and adapted ownership metadata | `STEP-01`, `STEP-03` | `CHK-02`, `CHK-03`, `EVID-05`, `EVID-06` | +| `C4-00` | `design.md` | No runtime artifact | `STEP-02` | `CHK-05` | + +## Approval Gates + +| ID | Action | Evidence | Limits | +| --- | --- | --- | --- | +| `AG-01` | Commit and push bounded corrections to branch `docs/issue-117-autonomy-fpf` and update draft PR #118 so required CI can run | `approved`: user message `2026-08-14`, “разрешаю и не надо меня спрашивать разрешение на коммитить и пушать” | This FT-117 recovery work on the existing branch/PR only; no merge, release, deploy, publication or unrelated mutation | + +## Порядок работ + +| Step | Actor | Goal / exact touchpoints | Verifies | Evidence | Blocked by | Stop condition | +| --- | --- | --- | --- | --- | --- | --- | +| `STEP-01` | agent | Verify three commit objects and both immutable diffs; reconcile only `memory-bank/features/FT-117/{README,brief,design,implementation-plan,feature-review-report}.md` | Recovery boundary and complete change-surface map | `EVID-05`, `EVID-06` | `PRE-01`, `PRE-02` | Git receipt differs or new scope appears | +| `STEP-02` | agent | Run exact `CHK-05` block and semantic acceptance against all canonical owners in Design Realization Mapping | `SC-01`–`SC-10`, `NEG-01`–`NEG-03` | `EVID-02`–`EVID-05` | `STEP-01` | Any scenario lacks one owner or bounded correction | +| `STEP-03` | agent | Run all local structural checks, project-specific leak check `rg -n 'FT-117|issue #117' template/memory-bank` expecting no matches, and record results outside frozen plan | `CHK-01`–`CHK-05` | `EVID-05` | `STEP-02` | Any command or expected result fails | +| `STEP-04` | agent | With `AG-01`, commit/push bounded recovery execution revision to the existing branch; wait for `CI / validate-template`; obtain independent implementation review of the delivered diff | Full validation profile and implementation convergence | `EVID-05`, `EVID-06`, `AG-01` | `STEP-03`, `AG-01` | CI/review not successful or scope differs | +| `STEP-05` | agent | After clean implementation verdict, prepare one terminal metadata revision: record verdict, set `brief.md: delivery_status: done` and archive this plan | Feature terminal candidate | `EVID-06` | `STEP-04` | Any non-metadata change or Done predicate remains open | +| `STEP-06` | agent | With `AG-01`, commit/push the terminal metadata revision, wait for `CI / validate-template`, and run final convergence read without further mutation | Feature terminal state | `EVID-05`, `EVID-06`, `AG-01` | `STEP-05`, `AG-01` | Final CI is not successful; then restore non-terminal status in a corrective revision | + +## Checkpoints + +| ID | Condition | Evidence | +| --- | --- | --- | +| `CP-01` | Draft and then active plan revisions have independent clean Plan Ready verdicts | `EVID-06` | +| `CP-02` | Git receipts, all local checks and semantic acceptance pass | `EVID-05` | +| `CP-03` | Execution revision CI and separate implementation review are clean; terminal metadata revision CI is also successful | `EVID-05`, `EVID-06` | + +## Stop Conditions / Fallback + +| ID | Trigger | Immediate action | Safe state | +| --- | --- | --- | --- | +| `STOP-01` | Candidate requires new requirement, runtime change or external action outside `AG-01` | Stop and repeat Task Routing | Existing draft PR remains unmerged | +| `STOP-02` | Draft or active Plan Ready review has critical/important finding | Keep plan `draft` or return it to `draft`; fix and freeze a new revision | `brief.md: planned` | +| `STOP-03` | Local check, CI or implementation review fails | Keep feature non-terminal; fix only in scope and repeat affected gates | Active plan plus open draft PR | +| `STOP-04` | Historical sequence would need to be represented as compliant | Preserve disclosed debt; do not rewrite history or backdate evidence | Recovery acceptance remains explicit | + +## Plan-local Evidence + +| Evidence | Carrier | Producer | Rule | +| --- | --- | --- | --- | +| `EVID-05` | Local command transcript and GitHub `CI / validate-template` check | agent / CI | Exact revision and pass criteria required | +| `EVID-06` | `feature-review-report.md` review history and PR review record | non-authoring reviewer, transcribed by delivery agent | Must name reviewer, frozen revisions, findings/dispositions and exact verdict; never treat self-review as independent | + +## Готово для приемки + +- The historical execution-order debt remains explicit. +- Draft and active plan revisions each have clean independent Plan Ready review. +- All exact local checks and `CI / validate-template` pass on the delivered revision. +- Independent implementation review has no open critical/important finding. +- No merge, release, deploy, publication or live-state mutation is performed. diff --git a/memory-bank/features/README.md b/memory-bank/features/README.md index f16e218..e1b7707 100644 --- a/memory-bank/features/README.md +++ b/memory-bank/features/README.md @@ -36,3 +36,5 @@ audience: humans_and_agents - [`FT-113/`](FT-113/README.md) — интеграция BDD behavior specification practice с существующими Feature/Use Case owners и verification traceability. +- [`FT-117/`](FT-117/README.md) — autonomous Structured Decision Protocol, + разделение decision authority и execution approval для issue #117. diff --git a/template/memory-bank/engineering/README.md b/template/memory-bank/engineering/README.md index 68bd993..0d28c35 100644 --- a/template/memory-bank/engineering/README.md +++ b/template/memory-bank/engineering/README.md @@ -18,7 +18,7 @@ audience: humans_and_agents - [UI Design Guide](ui-design-guide/README.md) — project-level index для shared и surface-specific UI references. Адаптируй его под public site, admin, mobile или другие реальные UI surfaces проекта. - [Testing Policy](testing-policy.md) — правила тестирования, обязательные automated tests, sufficient coverage. Отвечает на вопрос: когда feature обязана иметь test cases и когда допустим manual-only verify. - [Validation Profiles](validation-profiles.md) — независимая от delivery flow глубина validation: taxonomy, risk triggers, minimum evidence contract и canonical owner решения. -- [Autonomy Boundaries](autonomy-boundaries.md) — границы автономии агента: автопилот, супервизия, эскалация. Отвечает на вопрос: что агент может делать сам, а где должен остановиться и спросить. +- [Autonomy Boundaries](autonomy-boundaries.md) — autonomous-by-default правила, самодостаточный Structured Decision Protocol, вдохновлённый FPF, и настоящие Human Gates. Отвечает на вопрос: что агент решает и исполняет сам, а где нужны человеческие полномочия или принятие неконтролируемого риска. - [Coding Style](coding-style.md) — конвенции оформления кода, tooling и правила локальной сложности. - [Git Workflow](git-workflow.md) — git-конвенции: commits, ветки, PR и optional worktrees. - [ADR](../adr/README.md) — instantiated Architecture Decision Records проекта. diff --git a/template/memory-bank/engineering/autonomy-boundaries.md b/template/memory-bank/engineering/autonomy-boundaries.md index 5d0a35b..68a6ae0 100644 --- a/template/memory-bank/engineering/autonomy-boundaries.md +++ b/template/memory-bank/engineering/autonomy-boundaries.md @@ -2,11 +2,15 @@ title: Autonomy Boundaries doc_kind: engineering doc_function: canonical -purpose: "Границы автономии агента: что можно делать без подтверждения, где нужна супервизия, когда эскалировать." +purpose: "Границы автономии агента: что он решает и исполняет самостоятельно, как применяет Structured Decision Protocol и когда обязан эскалировать человеку." derived_from: - ../dna/governance.md canonical_for: - agent_autonomy_rules + - structured_decision_protocol + - decision_carrier_selection_rules + - execution_authorization_rules + - approval_evidence_rules - escalation_triggers - supervision_checkpoints status: active @@ -15,34 +19,248 @@ audience: humans_and_agents # Autonomy Boundaries +## Основной принцип + +Сложность, неоднозначность и наличие нескольких допустимых подходов сами по себе +не являются `Human Gate`. Агент сначала обязан попытаться принять решение через +описанный ниже Structured Decision Protocol, используя доступные canonical +facts, evidence и ограничения проекта. + +Structured Decision Protocol является полным обязательным контрактом. First +Principles Framework (FPF) или другая reasoning methodology могут углубить +анализ, но остаются опциональными: их отсутствие не блокирует решение, не +создаёт `Human Gate` и не меняет outcome semantics протокола. + +Разделяй три независимых вопроса: + +1. **Можно ли принять решение автономно?** Обычно да, если intent и полномочия + уже заданы, а риск можно ограничить. +2. **Где зафиксировать rationale?** В существующем issue, run ledger, design, + decision log или ADR в зависимости от долговечности решения. +3. **Можно ли исполнить действие?** Внешне-эффективное или необратимое действие + может требовать human approval, даже когда план и решение подготовлены + автономно. + +Human approval перед исполнением не заменяет reasoning, validation или rollback +plan. Structured Decision Protocol не отменяет явно заданные project policies, +обязательные approvals и границы полномочий. + ## Автопилот — делай без подтверждения -- Редактировать код в рамках задачи -- Запускать локальные тесты и линтеры -- Создавать ветки и worktrees -- Читать логи, метрики и error tracker -- Создавать и обновлять внутреннюю документацию -- Создавать и обновлять документацию в memory-bank +В пределах принятой задачи и project policy агент самостоятельно: + +- читает код, документацию, логи, метрики и error tracker; +- исследует существующие паттерны и собирает evidence; +- редактирует обычный non-risky код и внутреннюю документацию; +- запускает локальные тесты, линтеры, сборки и безопасные диагностические команды; +- готовит design, migration, rollout, backout и implementation plans; +- создаёт разрешённые project workflow ветки, worktrees, commits и pull requests; +- декомпозирует работу и уточняет execution sequencing без расширения принятого + outcome; +- исправляет дефекты, блокирующие accepted outcome в затронутом scope, если это + не меняет intent и не пересекает отдельную границу полномочий. + +Создание pull request не означает разрешение на merge. Агент может автономно +провести analysis, design, планирование, validation и подготовку rollback для +production, security, compliance, migration или integration change. Но сама +repository mutation, materially меняющая security/auth/trust/compliance +boundary, требует specific authority в текущей task или active project policy; +без неё это отдельный Human Gate. Такая authority также не означает разрешение +исполнить risk-bearing шаг над production/live state. + +## Когда применять Structured Decision Protocol + +Используй Structured Decision Protocol до выбора или изменения решения, когда: + +- нет одного очевидного существующего паттерна; +- паттерны или источники противоречат друг другу; +- есть несколько жизнеспособных подходов с разными trade-offs; +- меняются архитектура, contracts, schema, migration, trust boundary или + deployment model; +- требуется декомпозиция на delivery units или задача начинает выходить за + исходный scope; +- evidence неполно, а ошибка выбора materially влияет на outcome; +- повторные замечания или ошибки не уменьшаются и нужно пересмотреть исходную + гипотезу, план либо ограничения среды. + +Не запускай heavyweight-анализ для локального решения, которое следует +однозначному принятому паттерну и легко проверяется. + +## Structured Decision Protocol + +Каждая нетривиальная запись протокола различает четыре роли: + +- **authority source** — текущая task или active project policy, которая задаёт + допустимый scope и ограничения; +- **decision owner** — accountable role, принимающая решение среди допустимых + вариантов; +- **canonical carrier** — единственный durable artifact, владеющий rationale и + outcome; +- **execution approver / approval evidence** — отдельная роль и ссылка на + разрешение, только если конкретный execution step пересекает Human Gate. + +`Decision owner` не означает автоматически ни владельца carrier, ни execution +approver. Approval evidence фиксирует permission для шага исполнения и никогда +не меняет outcome протокола. + +Проведи минимально достаточный reasoning cycle: + +1. Зафиксируй decision, bounded context, scope, authority source и decision owner. +2. Отдели canonical facts и evidence от assumptions и unknowns. +3. Назови обязательные constraints, invariants, authority boundaries и budget; + исключи варианты, которые им не соответствуют. +4. Сформируй жизнеспособные варианты и явно запиши rejected alternatives; не создавай искусственные альтернативы, + если решение однозначно. +5. После удаления недопустимых вариантов примени tie-breakers в таком порядке: + существующий canonical pattern; наименьшее обратимое изменение; наименьший + blast radius; наименьшая operational и maintenance complexity; наиболее + сильная доступная verification. +6. Зафиксируй chosen option, rationale, evidence, значимые unknowns, risk + controls и confidence. +7. Запиши execution approver и approval evidence, если они требуются для + последующего execution step; иначе укажи `not required`. +8. Заверши одним outcome: `proceed`, `bounded_probe` или `escalate`. + +Если варианты остаются близкими после этих tie-breakers, выбирай автономно. +Tie-breakers не могут решить отсутствующий product/business value judgment. +Равенство вариантов не является причиной спрашивать человека. + +### `proceed` + +Выбирай, когда решение достаточно обосновано, находится в доступных полномочиях, +а риски закрыты validation, rollback и stop conditions. Продолжай работу без +дополнительного подтверждения. + +### `bounded_probe` + +Выбирай, когда ключевой unknown можно уменьшить безопасным экспериментом. +Эксперимент должен быть обратимым, иметь явный budget и stopping condition, не +изменять production/live state, не создавать внешний commitment и не обходить +обязательный approval. После probe обнови evidence и повтори protocol. + +До завершения Task Routing полный `bounded_probe` не выполняется: P0 допускает +только read-only сбор facts для классификации route. Если unknown требует +эксперимента, implementation discovery или изменения файлов, выбери Research +Flow; experiment и его stopping condition принадлежат этому lifecycle. + +### `escalate` + +Выбирай только когда после доступного анализа и безопасных probes отсутствует +допустимое автономное продолжение либо требуется человеческое полномочие или +value judgment. Unknown нельзя молча считать разрешением. + +## Где фиксировать решение + +Используй самый лёгкий canonical carrier, достаточный для срока жизни решения: + +- локальное обратимое execution decision — issue, task, PR или run ledger; +- feature- или epic-local durable decision — соответствующий design или + decision log; +- архитектурное, reusable, cross-feature или project-wide решение — ADR; +- разрешение на risk-bearing execution — approval record у соответствующего + шага, а не ADR по умолчанию. + +Удаление кода или файлов, декомпозиция на sub-issues и открытие PR сами по себе +не требуют ADR. Фиксируй rationale только когда оно существенно для review, +rollback или будущих решений. + +Зафиксируй минимальную запись structured decision: + +```text +Protocol: Structured Decision Protocol +Context: +Authority source: <текущая task или active project policy> +Decision owner: +Carrier: <единственный canonical record> +Facts / evidence: +Assumptions / unknowns: <явный список или none> +Constraints / authority boundaries: +Options / rejected alternatives: <допустимые варианты и причины отказа, если применимо> +Rationale: <почему выбранный вариант победил> +Risk controls: +Confidence: <достаточность основания> +Outcome: proceed | bounded_probe | escalate +Execution approval: +Probe budget / stop condition: +``` + +В записи должен быть ровно один `Outcome`. `Execution approval` не является +вторым outcome и не превращает `proceed` в разрешение на внешний или +risk-bearing шаг. + +## Human Gate — остановись и спроси + +Human approval или решение обязательно, когда: + +- нужно непосредственно изменить, удалить, backfill или repair + production/live data; +- нужно изменить production access, credentials, security/auth state или + выполнить другую труднообратимую security-sensitive операцию; +- нужно внести repository/code/config mutation, materially меняющую + security/auth/trust/compliance boundary, и текущая task или active project + policy не даёт specific authority для такого изменения; +- выполняется реальная финансовая, юридически значимая или иная необратимая + внешняя операция; +- нужно отправить сообщение, опубликовать материал или принять обязательство от + имени человека или организации; +- merge, release или deployment не были уже явно разрешены текущей задачей или + действующей project policy; +- закон, compliance, договор или project policy требует конкретного human + approver; +- отсутствует canonical product/business priority или value judgment, без + которого варианты нельзя упорядочить; +- требуемый outcome выходит за выданный scope, budget или полномочия; +- ни один вариант не сохраняет обязательные invariants либо риск нельзя + ограничить validation, staged execution, rollback и stop conditions; +- Structured Decision Protocol завершился `escalate`. + +Human Gate применяется к конкретному decision или execution step. Остальную +подготовку, исследование, validation и безопасную работу продолжай, если они не +зависят от ответа. + +### Valid approval evidence + +Разрешение текущей task или active project policy считается approval evidence +только если запись одновременно: + +- называет конкретное действие или узкий класс действий; +- называет target, environment или external system; +- задаёт scope и существенные limits; +- исходит от canonical task или active policy с понятным owner; +- является актуальной и не отменена более специфичной policy, compliance rule, + contract или revocation; +- прикреплена к точному execution gate. + +Широкое, неоднозначное, выведенное из контекста или устаревшее разрешение не +является approval evidence. Policy может дополнительно требовать fresh approval +для каждого execution. + +## Что не является Human Gate -## Супервизия — делай, но покажи на контрольной точке +Не эскалируй только потому, что: -- Архитектурные решения, новые сервисы и изменение контрактов — покажи план до начала -- Изменение схемы БД и data migration — покажи миграцию до запуска -- Удаление кода или файлов — покажи что удаляешь и почему -- PR в default branch — покажи diff и результаты тестов -- Изменение конфигурации, маршрутизации или deployment contract — покажи изменения -- Декомпозиция задачи на sub-issues — покажи разбиение +- задача сложная, новая или требует архитектурного решения; +- существует несколько допустимых реализаций; +- нужен ADR, migration plan, rollout plan или decomposition; +- можно продолжить через безопасный `bounded_probe`; +- CI ещё выполняется или внешний check находится в ожидаемом состоянии `WAIT`; +- агент может автономно подготовить change, но пока не имеет разрешения только + на его финальный внешне-эффективный шаг. -## Эскалация — остановись и спроси +## Контракт эскалации -- Неясные или противоречивые бизнес-требования -- Выбор между несколькими равноценными подходами с разными trade-offs -- Любые действия в production или against live data -- Отправка сообщений пользователям или внешним контрагентам -- Изменение платёжных, security, auth или compliance-sensitive интеграций -- Конфликтующие паттерны в кодовой базе — не угадывай, спроси какой правильный -- Задача выходит за scope issue — не расширяй молча +Перед запросом человека зафиксируй: -## Правило эскалации +- точный заблокированный decision или execution step; +- outcome протокола и уже проверенные варианты; +- canonical facts, evidence и остающийся unknown; +- почему `proceed` и `bounded_probe` недопустимы; +- конкретное требуемое решение или approval; +- безопасное состояние и работу, которую можно продолжать независимо. -Если замечания или ошибки не уменьшаются после 2-3 итераций, проблема может быть не в коде, а в upstream-требованиях, плане или ограничениях среды. В этом случае агент останавливает цикл и предлагает вернуться на предыдущий этап. +Если замечания или ошибки не уменьшаются после заранее ограниченного числа +итераций, не повторяй тот же цикл. Пересмотри hypothesis, upstream requirements, +plan и environment constraints через Structured Decision Protocol. Эскалируй +только если этот разбор не дал bounded продолжения или выявил +authority/value/risk boundary, а не из-за самого факта +исчерпания итераций. diff --git a/template/memory-bank/engineering/validation-profiles.md b/template/memory-bank/engineering/validation-profiles.md index 8e6b32f..8fc4cb0 100644 --- a/template/memory-bank/engineering/validation-profiles.md +++ b/template/memory-bank/engineering/validation-profiles.md @@ -33,7 +33,7 @@ Delivery flow и validation profile отвечают на разные вопр | `documentation` | Меняется только документация или другой non-runtime artifact; executable behavior, contracts, production config и release path не меняются. | | `low-risk` | Локальное executable change следует известному паттерну, имеет малый blast radius и не активирует triggers ниже. | | `standard` | Default для executable change, которое не доказано как `low-risk` и не активирует более сильный профиль. | -| `high-risk` | Текущий run непосредственно выполняет рискованное действие над production/live state: изменяет или удаляет production data, production access/security state, совершает реальную финансовую или другую необратимую внешнюю операцию. Требуются explicit approval и отдельная проверка неавтором mutation. | +| `high-risk` | Текущий run непосредственно выполняет рискованное действие над production/live state: изменяет или удаляет production data, production access/security state, совершает реальную финансовую или другую необратимую внешнюю операцию. Подготовка решения автономна; перед risk-bearing execution step требуются explicit approval и отдельная проверка неавтором mutation. | | `release-deployment` | Основной change surface — production config, build/release artifact, deployment или rollback path без отдельного `high-risk` trigger. | Это не количественный risk score. `documentation < low-risk < standard`; `high-risk` и `release-deployment` — усиленные специализированные профили. Если применимы оба, выбери `high-risk` и добавь все release/deployment obligations из соответствующей строки minimum contract. @@ -44,7 +44,7 @@ Delivery flow и validation profile отвечают на разные вопр - `documentation` допустим только при отсутствии executable, contract, config и release impact; - `low-risk` допустим, когда change локален, rollback очевиден, affected test surface известен и нет triggers из таблицы; -- новый или изменённый public API, event, schema, file format, security/auth boundary, financial calculation, persistent-data model, migration plan, concurrency/locking/idempotency semantics или cross-system integration требует как минимум `standard`; эти code/design triggers сами по себе не повышают profile до `high-risk`; +- новый или изменённый public API, event, schema, file format, security/auth/trust/compliance boundary, financial calculation, persistent-data model, migration plan, concurrency/locking/idempotency semantics или cross-system integration требует как минимум `standard`; эти code/design triggers сами по себе не повышают profile до `high-risk`, но material security/compliance boundary mutation требует specific authority по canonical Human Gate; - `high-risk` выбирай только когда текущий run должен непосредственно выполнить risk-bearing действие в production/live environment: изменить, удалить, backfill или repair production data; изменить production access/security state; провести реальную финансовую операцию; либо вызвать другую необратимую external effect. Ожидаемая будущая поставка code change не является таким действием; - production config, build/release artifact, deployment или rollback path повышает до `release-deployment`; если в том же run выполняется `high-risk` действие, выбери `high-risk` и добавь все release/deployment obligations из соответствующей строки. @@ -58,6 +58,21 @@ Delivery flow и validation profile отвечают на разные вопр 4. Отсутствие возможности выполнить обязательную проверку создаёт blocker или approved manual-only gap по [`testing-policy.md`](testing-policy.md), но само по себе не снижает profile. 5. Profile задаёт floor. Project-specific testing policy, incident controls, regulatory rules или reviewer могут требовать больше. +Выбор более сильного profile, analysis, design, planning, rehearsal, staging, +validation и подготовка rollback выполняются автономно. Обычная implementation +также не требует human approval только из-за сложности или риска будущего +изменения. Approval проверяется непосредственно перед тем execution step, +который пересекает canonical Human Gate из +[`autonomy-boundaries.md`](autonomy-boundaries.md); таким шагом может быть как +material security/compliance boundary mutation в repository без specific task +authority, так и последующая risk-bearing операция над production/live state. +Approval evidence может быть явным разрешением в текущей task либо применимой +active project policy, если она однозначно называет действие, environment и +границы разрешения. Неясное или общее разрешение не считается approval. +Structured Decision Protocol может выбрать подход и усилить controls, но не +может отменить обязательный approval или понизить profile ниже сработавшего +trigger. + ## Minimum Validation And Evidence Contract `Обычный review` не требует отдельного неавторского reviewer: это convergence @@ -71,9 +86,9 @@ Human approval — отдельный gate для risk-bearing action и не з | --- | --- | --- | --- | --- | --- | --- | --- | | `documentation` | Link, schema/frontmatter, example или docs build checks, применимые к changed docs | Targeted documentation lint/build | Все required documentation jobs | Semantic read-through; render evidence, если layout влияет на результат | Обычный review; отдельный approval только по project policy | Не требуется; если меняется published release path, переклассифицировать | Обычный review достаточен | | `low-risk` | Targeted regression для changed behavior; существующие nearest tests | Targeted affected suite и repository lint/typecheck, если применимы | Все required jobs для change | Только для непокрываемой automation части с явной процедурой | Обычный review; manual-only gap требует указанного approver | Понятный локальный revert; staged rollout не обязателен | Simplify/convergence pass исполнителя и обычный review | -| `standard` | Changed behavior, ближайший regression path, изменённые contracts/integration boundaries и material negative cases | Все affected unit/integration/contract suites | Полный required CI set | Acceptance evidence и оформленные manual-only gaps | Approval для manual-only critical gap и внешне-эффективных действий | Rollback path для runtime change; rollout checks, если delivery не атомарна | Final convergence pass исполнителя и обычный review | -| `high-risk` | Все surfaces, необходимые для безопасного direct production/live action; critical failure modes; recovery rehearsal или deterministic substitute | Полный релевантный набор для данного действия; невозможное явно блокирует или получает approval | Все required CI плюс доступные specialized gates | Evidence по действию, critical path, failure/recovery case и rehearsal | Human approval профиля, manual-only gaps и risk-bearing execution step | Явные staged rollout, observability signals, stop conditions и проверенный backout/recovery plan | Separate non-authoring actor проверяет затронутый production-risk domain; финальный convergence pass обязателен | -| `release-deployment` | Build/package/config validation, deploy/rollback automation и smoke/health checks | Release artifact/config checks и staging rehearsal, где доступно | Required release/deployment jobs | Artifact identity, staging/smoke results и production signals | Human approval перед production или live-data action | Явные rollout units, stop signals, rollback owner и fastest safe rollback | Separate review release plan/config и post-deploy convergence обязательны | +| `standard` | Changed behavior, ближайший regression path, изменённые contracts/integration boundaries и material negative cases | Все affected unit/integration/contract suites | Полный required CI set | Acceptance evidence и оформленные manual-only gaps | Approval для manual-only critical gap, внешне-эффективных действий и material security/compliance boundary mutation без specific task/policy authority | Rollback path для runtime change; rollout checks, если delivery не атомарна | Final convergence pass исполнителя и обычный review | +| `high-risk` | Все surfaces, необходимые для безопасного direct production/live action; critical failure modes; recovery rehearsal или deterministic substitute | Полный релевантный набор для данного действия; невозможное явно блокирует или получает approval | Все required CI плюс доступные specialized gates | Evidence по действию, critical path, failure/recovery case и rehearsal | Human approval для downgrade, manual-only gaps и самого risk-bearing execution step; выбор профиля и подготовка автономны | Явные staged rollout, observability signals, stop conditions и проверенный backout/recovery plan | Separate non-authoring actor проверяет затронутый production-risk domain; финальный convergence pass обязателен | +| `release-deployment` | Build/package/config validation, deploy/rollback automation и smoke/health checks | Release artifact/config checks и staging rehearsal, где доступно | Required release/deployment jobs | Artifact identity, staging/smoke results и production signals | Approval перед production execution только когда шаг пересекает canonical Human Gate; task/project-policy preauthorization может быть approval evidence. Live-data mutation дополнительно включает `high-risk` obligations | Явные rollout units, stop signals, rollback owner и fastest safe rollback | Separate review release plan/config и post-deploy convergence обязательны | Конкретные frameworks, команды, suites, CI job names и evidence paths не принадлежат taxonomy: их задают project-specific [`testing-policy.md`](testing-policy.md), execution plan или routing record выбранного flow. diff --git a/template/memory-bank/flows/README.md b/template/memory-bank/flows/README.md index c312bbe..41ff74a 100644 --- a/template/memory-bank/flows/README.md +++ b/template/memory-bank/flows/README.md @@ -26,7 +26,7 @@ audience: humans_and_agents Каталог `memory-bank/flows/` содержит reusable process-layer для шаблона: lifecycle rules, taxonomy стабильных идентификаторов и governed templates. -- [Task Routing](routing.md) — порядок выбора flow, routing predicates, повторный routing и Human Routing. +- [Task Routing](routing.md) — порядок выбора flow, routing predicates, повторный routing и Human Routing только после Structured Decision Protocol outcome `escalate`. - [Task Context Priming](priming/README.md) — общий P0/P1/P2 contract, universal DNA baseline и per-process YAML manifests. - [Research & Discovery Flow](research.md) — evidence-backed lifecycle research-задач, от question framing до decision и handoff без преждевременного delivery. - [Incident And PIR Flow](incident.md) — containment, recovery, timeline, RCA, PIR и prevention work. diff --git a/template/memory-bank/flows/bug-fix.md b/template/memory-bank/flows/bug-fix.md index bb1d874..774e1a4 100644 --- a/template/memory-bank/flows/bug-fix.md +++ b/template/memory-bank/flows/bug-fix.md @@ -9,6 +9,7 @@ derived_from: - priming/context-priming.md - ../engineering/testing-policy.md - ../engineering/validation-profiles.md + - ../engineering/autonomy-boundaries.md canonical_for: - bug_fix_entry_contract - bug_fix_priming_inputs @@ -42,7 +43,15 @@ report или linked delivery task. - [ ] operational incident уже contained или передан в [`Incident Flow`](incident.md) - [ ] bug report или связанная delivery task фиксирует validation profile decision -Если нет ни доступного источника уже принятого expected behavior, ни зафиксированного решения человека, Entry Gate не выполнен: зафиксируй вопрос и риск через [Human Routing](routing.md#human-routing). До решения `Human Gate` не начинай Analysis And Fix и не изменяй код; после решения повтори Task Routing. +Если нет ни доступного источника уже принятого expected behavior, ни +зафиксированного решения человека, Entry Gate не выполнен. Не изобретай expected +behavior и не начинай Analysis And Fix как bug fix. Примени +[`Structured Decision Protocol`](../engineering/autonomy-boundaries.md#structured-decision-protocol) +и повтори Task Routing: доступный evidence-backed answer может потребовать +Research Flow, а новое желаемое поведение — Feature Flow. Используй +[Human Routing](routing.md#human-routing) только при outcome `escalate`, когда +выбор действительно требует отсутствующего product/value decision или +дополнительных полномочий. ## Flow diff --git a/template/memory-bank/flows/epic.md b/template/memory-bank/flows/epic.md index 2f5a72b..a540a3c 100644 --- a/template/memory-bank/flows/epic.md +++ b/template/memory-bank/flows/epic.md @@ -9,6 +9,7 @@ derived_from: - routing.md - priming/context-priming.md - feature.md + - ../engineering/autonomy-boundaries.md canonical_for: - epic_directory_structure - epic_priming_inputs @@ -31,7 +32,7 @@ audience: humans_and_agents Epic - это управляемая инициатива крупнее одной delivery-feature. Он задаёт общий intent, границы, roadmap, решения, риски и subissue registry, но не подменяет feature package и не содержит code-level execution plan. Если Epic route уже выбран, но facts ещё недостаточны для полного setup, flow начинается с **Epic Intake**; его состояние **Epic Proposal** фиксируется в обязательном для Intake `brief.md`. `brief.md` можно не создавать только при пропуске Intake и прямом переходе к Bootstrap Epic. -FPF-основание: +Основание структуры: - **Bounded Contexts**: epic делит большую инициативу на смысловые контексты и delivery-slices, чтобы не смешивать бизнес, операции, финансы, UI/API и реализацию. - **Strict Distinction**: epic, feature, PRD, use case, ADR и implementation plan имеют разные owners и не должны подменять друг друга. @@ -247,7 +248,7 @@ Epic quality is a Q-Bundle, not one scalar. | Traceability | Source docs, decisions, requirements, UC and subissues linked by stable IDs | Can a reviewer trace each planned feature back to evidence? | | Decomposability | Bounded contexts and slices are separated | Can we create one delivery issue without dragging the whole epic? | | Roadmap clarity | Waves, dependencies, gates and stop rules are explicit | Does the team know what should happen first and why? | -| Decision provenance | Если существуют non-trivial local decisions, `decision-log.md` связывает facts, FPF reasoning и consequences | Are existing local decisions backed by evidence rather than preference? | +| Decision provenance | Если существуют non-trivial local decisions, `decision-log.md` связывает facts, Structured Decision Protocol reasoning и consequences | Are existing local decisions backed by evidence rather than preference? | | Scope control | Non-scope and stop rules are explicit | Can we prevent accidental expansion during delivery? | | Risk governance | `risks.md` lists risks, controls and owners | Are high-impact financial/operator risks visible before code? | | Execution handoff | `subissues.md` and roadmap define feature-package inputs | Can a slice owner start without re-reading the whole epic? | @@ -272,7 +273,7 @@ Epic quality is a Q-Bundle, not one scalar. 1. Epic may define roadmap waves, but not file-level execution steps. 2. Epic may define subissue candidates, but does not make them implementation-ready until a delivery issue and feature package exist. -3. Epic may close local decisions with FPF and evidence. If a decision changes global project architecture, create ADR. +3. Epic may close local decisions with Structured Decision Protocol and evidence. If a decision changes global project architecture, create ADR. 4. Feature package, созданный из epic, должен ссылаться на релевантные `EP-*` docs и сохранять stable IDs вместо копирования всего scope. `brief.md` импортирует problem/scope refs; `design.md` или ADR импортирует epic-local decisions, когда они влияют на solution space. 5. If a feature discovers a new epic-level fact, update the epic owner document first, then update the feature. 6. Epic Intake может называть только candidate `BR-SLICE-*`. До `Roadmap Ready -> Execution` нельзя создавать delivery `FT-*` package на основании intake proposal. diff --git a/template/memory-bank/flows/feature.md b/template/memory-bank/flows/feature.md index e9ee157..e60afa3 100644 --- a/template/memory-bank/flows/feature.md +++ b/template/memory-bank/flows/feature.md @@ -10,6 +10,7 @@ derived_from: - priming/context-priming.md - behavior-specification.md - ../engineering/validation-profiles.md + - ../engineering/autonomy-boundaries.md canonical_for: - feature_directory_structure - feature_priming_inputs @@ -185,7 +186,10 @@ stakeholder/concern coverage поверх canonical facts, а не пять но | Scenarios (+1) | Всегда: каждый `SC-*` участвует в Cross-View Correspondence | Никогда | Если evidence недостаточно, чтобы доказать `N/A`, view остается `covered` и -анализ продолжается либо unresolved applicability проходит Human Gate. +анализ продолжается. Неопределённость applicability сама по себе не является +Human Gate; примени +[`Structured Decision Protocol`](../engineering/autonomy-boundaries.md#structured-decision-protocol) +и эскалируй только при outcome `escalate`. Logical View и Scenarios всегда получают `covered`. Process, Development и Physical получают `covered` по predicates выше либо обоснованный `N/A`. @@ -347,7 +351,13 @@ flowchart LR ### Upstream Ready → Plan Ready -Plan Ready artifact-review convergence допускает не более пяти review-improve итераций. Последняя итерация с исправлениями не считается clean verdict без последующего re-review; исчерпание budget оставляет gate непройденным и требует replan либо Human Gate. +Plan Ready artifact-review convergence допускает не более пяти review-improve +итераций. Последняя итерация с исправлениями не считается clean verdict без +последующего re-review; исчерпание budget оставляет gate непройденным. Примени +[`Structured Decision Protocol`](../engineering/autonomy-boundaries.md#structured-decision-protocol), +пересмотри hypothesis, upstream facts, plan и review scope; продолжай через +обоснованный replan или `bounded_probe`. Human Gate нужен только при outcome +`escalate`. - [ ] агент выполнил grounding до sequencing: прошёлся по текущему состоянию системы против зафиксированного immutable commit SHA repository revision и сохранил `GRND-*` evidence в `implementation-plan.md`; `HEAD`, branch name и tag не допускаются - [ ] `implementation-plan.md` содержит упорядоченный `Implementation Priming`: exact repo-relative paths или stable external sources, section/symbol, `GRND-*` refs, purpose и required `STEP-*`; categories, globs, `TODO` и предполагаемые paths не допускаются @@ -440,7 +450,7 @@ Plan Ready artifact-review convergence допускает не более пят 13. Если support doc выявляет конфликт с canonical owner, конфликт нельзя решать внутри support doc: обнови `brief.md`, непосредственный design-pack owner, external dependency или `implementation-plan.md` по ownership. 14. Если численный target threshold относится только к одной delivery-единице, canonical owner — соответствующий `brief.md`. Поднимать такой KPI в project-level документ можно только после того, как он стал shared upstream fact для нескольких feature. 15. Хороший `implementation-plan.md` начинается с discovery context: relevant paths, local reference patterns, unresolved questions, test surfaces и execution environment должны быть зафиксированы до sequencing изменений. -16. Для рискованных, необратимых или внешне-эффективных действий `implementation-plan.md` должен явно описывать human approval gates и не скрывать их внутри prose шага. +16. Для действий, пересекающих canonical Human Gate из [autonomy boundaries](../engineering/autonomy-boundaries.md#human-gate--остановись-и-спроси), `implementation-plan.md` должен явно отделять автономные preparation/validation steps от требующего approval execution step и не скрывать gate внутри prose шага. 17. Если feature исполняет часть upstream initiative, `brief.md` должен ссылаться только на релевантные upstream artifacts и imported IDs, а не копировать весь upstream scope. Если используются upstream solution decisions, `design.md` или ADR ссылается на их canonical owner. 18. Upstream roadmap, cross-feature risks и delivery-unit registries принадлежат upstream owner-документам, а не feature package. 19. **Artifact review и implementation review различаются.** Artifact review проверяет governed brief/design/plan, их grounding, ownership, completeness и traceability до lifecycle gate. Implementation review проверяет delivered code и repository diff после execution. Они имеют разные reviewed revisions, findings и verdicts и не заменяют друг друга. diff --git a/template/memory-bank/flows/priming/bug-fix.yaml b/template/memory-bank/flows/priming/bug-fix.yaml index 368fc99..7d1ae9b 100644 --- a/template/memory-bank/flows/priming/bug-fix.yaml +++ b/template/memory-bank/flows/priming/bug-fix.yaml @@ -5,6 +5,7 @@ stages: - memory-bank/prd/*.md - memory-bank/use-cases/*.md - memory-bank/domain/*.md + - memory-bank/engineering/autonomy-boundaries.md - memory-bank/engineering/validation-profiles.md - memory-bank/engineering/testing-policy.md analysis_fix: diff --git a/template/memory-bank/flows/priming/feature.yaml b/template/memory-bank/flows/priming/feature.yaml index b067f26..39cfa7d 100644 --- a/template/memory-bank/flows/priming/feature.yaml +++ b/template/memory-bank/flows/priming/feature.yaml @@ -8,6 +8,7 @@ stages: - memory-bank/prd/*.md - memory-bank/product/*.md - memory-bank/domain/*.md + - memory-bank/engineering/autonomy-boundaries.md - memory-bank/engineering/validation-profiles.md - memory-bank/flows/templates/feature/README.md - memory-bank/flows/templates/feature/brief.md diff --git a/template/memory-bank/flows/priming/research.yaml b/template/memory-bank/flows/priming/research.yaml index 2a58334..cac6ae6 100644 --- a/template/memory-bank/flows/priming/research.yaml +++ b/template/memory-bank/flows/priming/research.yaml @@ -3,6 +3,7 @@ process: research stages: bootstrap: - memory-bank/research/README.md + - memory-bank/engineering/autonomy-boundaries.md - memory-bank/flows/templates/research/README.md - memory-bank/flows/templates/research/package-README.md - memory-bank/flows/templates/research/brief.md diff --git a/template/memory-bank/flows/research.md b/template/memory-bank/flows/research.md index 010230c..7854d6c 100644 --- a/template/memory-bank/flows/research.md +++ b/template/memory-bank/flows/research.md @@ -8,6 +8,7 @@ derived_from: - ../dna/frontmatter.md - routing.md - priming/context-priming.md + - ../engineering/autonomy-boundaries.md canonical_for: - research_directory_structure - research_priming_inputs @@ -144,6 +145,14 @@ When a durable fact is accepted, promote it before closing the research package: 7. A technical spike may contain disposable code or benchmark commands, but production implementation requires a new routed delivery flow. 8. If findings change an active canonical fact, update that owner first; research artifacts remain derived evidence. +9. Если P0 или уже выбранный delivery flow выявил unknown, требующий + `bounded_probe`, сначала явно выбери или повторно выбери Research Flow по + Task Routing. Probe обязан вернуть decision question, collected evidence, + limitations и terminal disposition в originating decision context. После + handoff originating context повторяет Structured Decision Protocol и Task + Routing; Research не выбирает delivery route молча и не подменяет его + implementation plan. + ## Stable Identifiers | Prefix | Meaning | Owner | diff --git a/template/memory-bank/flows/routing.md b/template/memory-bank/flows/routing.md index d6c0b94..2bb021f 100644 --- a/template/memory-bank/flows/routing.md +++ b/template/memory-bank/flows/routing.md @@ -71,7 +71,9 @@ Issue / Task | доставляет planned engineering / | operations outcome? ------------> Feature Flow | - +-- Неясно / высокий риск ----------> Human Routing + +-- Route не выбран после structured decision, + нужен authority/value decision + или риск не контролируется? ----> Human Routing ``` ## Routing Predicates @@ -85,7 +87,7 @@ Issue / Task | 5 | Работа крупнее одной delivery-feature и требует общего roadmap, cross-feature risk register или нескольких delivery units? | [`Epic Flow`](epic.md) | | 6 | Цель — изменить внутреннюю структуру при сохранении поведения? | [`Refactoring Flow`](refactoring.md) | | 7 | Задача укладывается в одну delivery-unit и создаёт или materially меняет пользовательское поведение либо доставляет плановое infrastructure, engineering или operations изменение с проверяемым outcome? | [`Feature Flow`](feature.md) | -| 8 | Маршрут остаётся неоднозначным или риск не контролируется? | Human Routing | +| 8 | После P0-safe Structured Decision Protocol и автономных tie-breakers route всё ещё нельзя обосновать, Research Flow не может законно закрыть unknown, требуется authority/value decision или риск не контролируется? | Human Routing | ### Small Change Gate @@ -114,7 +116,14 @@ Issue / Task Если признаки Epic route уже подтверждены, но problem, outcome, границы или evidence ещё недостаточны для canonical `charter.md`, задача всё равно маршрутизируется в [`Epic Flow`](epic.md). В этом случае Epic Flow начинается с `Epic Intake`: создаётся proposal package с `README.md` и `brief.md`, а недостающие факты фиксируются как open questions. -Неполнота epic facts сама по себе не является основанием для `Human Routing`. Human gate нужен только тогда, когда нельзя обоснованно выбрать route, требуется продуктовое решение о самом направлении инициативы или доступный риск нельзя контролировать intake boundaries. +Неполнота epic facts сама по себе не является основанием для `Human Routing`. +Сначала примени Structured Decision Protocol из +[`autonomy-boundaries.md`](../engineering/autonomy-boundaries.md) в пределах P0. +Если missing facts требуют эксперимента или broad evidence collection, выбери +Research Flow, а не выполняй probe до routing. Human gate нужен только когда +результатом стал `escalate`: route нельзя обосновать без отсутствующего +product/value decision, нужны дополнительные полномочия или риск нельзя +контролировать intake boundaries. ## Rerouting Rules @@ -129,16 +138,28 @@ Issue / Task ## Human Routing -Следуй canonical triggers из [`../engineering/autonomy-boundaries.md`](../engineering/autonomy-boundaries.md). Для routing дополнительно запрашивай решение человека, когда выбор flow требует продуктового решения, риск нельзя контролировать существующими gates или несколько route остаются одинаково правдоподобными после доступного исследования. +Следуй canonical Structured Decision Protocol и triggers из +[`../engineering/autonomy-boundaries.md`](../engineering/autonomy-boundaries.md). +Не отправляй задачу в Human Routing только из-за сложности, неполных данных или +нескольких правдоподобных routes. Сначала используй routing predicates, +canonical facts и автономные tie-breakers. P0 остаётся read-only: если unknown +требует эксперимента, implementation discovery или изменения файлов, выбери +Research Flow и выполни `bounded_probe` внутри его lifecycle. + +Запрашивай решение человека, только когда outcome протокола — `escalate`: выбор flow +требует отсутствующего product/business value judgment или дополнительных +полномочий, ни один route не сохраняет обязательные constraints либо риск нельзя +контролировать существующими gates. ### Human Routing Priming Inputs Прочитай [`routing.yaml`](priming/routing.yaml) и выполни source set `human_routing`. -Перед запросом человека зафиксируй competing routes, evidence, unknown или -approval trigger и точный вопрос. Не продолжай delivery или broad research до -решения; после него повтори Task Routing. +Перед запросом человека зафиксируй competing routes, применённые decision +criteria, P0 evidence, unknown, причину неприменимости Research Flow, approval +trigger и точный вопрос. До решения не начинай delivery, broad research, design +или изменение файлов; после него повтори Task Routing. ## Outcome / Exit Contract @@ -154,7 +175,9 @@ approval trigger и точный вопрос. Не продолжай delivery - для Epic route запись дополнительно указывает `Epic Intake`, когда facts ещё недостаточны для прямого `Bootstrap Epic`; - для Research route запись указывает decision question, decision owner и stopping condition; - для применимого delivery flow его canonical owner фиксирует отдельный validation profile decision по [`validation-profiles.md`](../engineering/validation-profiles.md); это downstream evidence выбора flow, а не дополнительный route; -- для `Human Routing` зафиксированы вопрос, риск или конкурирующие routes. +- для `Human Routing` зафиксированы outcome `escalate`, вопрос, риск или + конкурирующие routes и причина, по которой routing criteria, автономные + tie-breakers и Research Flow не дают допустимого продолжения. ### Terminal State diff --git a/template/memory-bank/flows/templates/epic/decision-log.md b/template/memory-bank/flows/templates/epic/decision-log.md index cb351ad..cdc3684 100644 --- a/template/memory-bank/flows/templates/epic/decision-log.md +++ b/template/memory-bank/flows/templates/epic/decision-log.md @@ -2,7 +2,7 @@ title: "EP-XXX: Decision Log Template" doc_kind: governance doc_function: template -purpose: "Шаблон epic-local decision log for decisions backed by evidence/FPF that do not require global ADR." +purpose: "Шаблон epic-local decision log for decisions backed by evidence and Structured Decision Protocol that do not require global ADR." derived_from: - ../../epic.md status: active @@ -29,7 +29,7 @@ must_not_define: # EP-XXX: Decision Log -## FPF Reading Rule +## Structured Decision Reading Rule Record facts, assumptions, reasoning and consequences separately.