diff --git a/memory-bank/.lock b/memory-bank/.lock index 7957b45..a9da99e 100644 --- a/memory-bank/.lock +++ b/memory-bank/.lock @@ -169,11 +169,9 @@ "payload_mode": "100644" }, "memory-bank/features/README.md": { - "ownership": "managed", + "ownership": "adapted", "base_digest": "sha256:b566792f535872b80432e6c5290a618aac32e3970c63d5f50fc8d8f863a3d312", - "payload_digest": "sha256:b566792f535872b80432e6c5290a618aac32e3970c63d5f50fc8d8f863a3d312", - "base_mode": "100644", - "payload_mode": "100644" + "base_mode": "100644" }, "memory-bank/flows/README.md": { "ownership": "managed", diff --git a/memory-bank/domain/glossary.md b/memory-bank/domain/glossary.md index b1e85d8..e7a6825 100644 --- a/memory-bank/domain/glossary.md +++ b/memory-bank/domain/glossary.md @@ -21,6 +21,7 @@ canonical_for: | Term | Meaning | Context | Do not confuse with | | --- | --- | --- | --- | | `domain-term` | Что термин означает в проекте | Где используется | Похожие product, UI или technical terms | +| `task-capsule` | Package-local persisted handoff containing the current route/stage, canonical owner references, resumable actions, assumptions, risks, evidence, stop conditions and the exact next action for safely continuing an active task across sessions, machines or roles. | Feature and Epic orchestration; contract: [`task-capsule.md`](../../template/memory-bank/flows/task-capsule.md) | A lifecycle owner document, a session transcript or a task registry; those may provide facts or projections but do not replace the capsule contract. | ## Naming Rules diff --git a/memory-bank/features/FT-109/README.md b/memory-bank/features/FT-109/README.md new file mode 100644 index 0000000..9e2400a --- /dev/null +++ b/memory-bank/features/FT-109/README.md @@ -0,0 +1,19 @@ +--- +title: "FT-109: Task Capsule Contract" +doc_kind: feature +doc_function: index +purpose: "Bootstrap-safe navigation for the Task Capsule contract delivery unit." +derived_from: + - ../../../template/memory-bank/flows/feature.md + - brief.md +status: active +audience: humans_and_agents +--- + +# FT-109: Task Capsule Contract + +- [`brief.md`](brief.md) — canonical problem space, scope, profile and verify contract. +- [`design.md`](design.md) — selected storage boundary, schema and ownership mapping. +- [`implementation-plan.md`](implementation-plan.md) — grounded execution and validation plan. +- [`task-capsule.md`](task-capsule.md) — active run state for this feature package. +- [`review-record.md`](review-record.md) — external carrier for bounded review verdicts. diff --git a/memory-bank/features/FT-109/brief.md b/memory-bank/features/FT-109/brief.md new file mode 100644 index 0000000..b3106c8 --- /dev/null +++ b/memory-bank/features/FT-109/brief.md @@ -0,0 +1,124 @@ +--- +title: "FT-109: Task Capsule Contract" +doc_kind: feature +doc_function: canonical +purpose: "Define a generic persisted Task Capsule contract that lets Feature and Epic work resume safely without replaying the full transcript." +derived_from: + - ../../../template/memory-bank/flows/feature.md + - ../../../template/memory-bank/flows/task-capsule.md + - ../../../template/memory-bank/flows/routing.md + - ../../../template/memory-bank/engineering/validation-profiles.md + - ../../../template/memory-bank/flows/templates/process/session-handoff.md +status: active +delivery_status: done +audience: humans_and_agents +must_not_define: + - runtime_orchestration + - temporal_integration + - automatic_validation_implementation +--- + +# FT-109: Task Capsule Contract + +## What + +### Problem + +Feature and Epic flows have canonical documents, but an interrupted session +does not yet have one compact, durable handoff contract that identifies the +current stage, exact next action and evidence without copying those owners. + +### Outcome + +| Metric ID | Metric | Baseline | Target | Measurement method | +| --- | --- | --- | --- | --- | +| MET-01 | Resume state completeness | No generic capsule contract | All required fields, owners and resume inputs documented | Read-through against issue acceptance and flow owners | + +### Scope + +- `REQ-01` Document a schema/example containing task identity, route/stage, roles, artifact refs, actions, assumptions, risks, evidence, stop conditions and handoff diagnostic. +- `REQ-02` Define Feature and Epic storage locations, field ownership and lifecycle update rules. +- `REQ-03` Map the capsule to existing Feature/Epic lifecycle documents and session handoff continuation inputs. +- `REQ-04` Preserve canonical owners and state that any registry is projection-only. + +### Non-Scope + +- `NS-01` Runtime orchestration, Temporal integration, queues, retries or automatic resume. +- `NS-02` Automatic validators or mutations of canonical owner documents. +- `NS-03` Project-specific roles, downstream implementation and parent issue closure. + +## Constraints / Assumptions + +- `ASM-01` Generic rules belong in `template/memory-bank/`; FT-109 is the project-local delivery owner and evidence package. +- `ASM-02` Existing Feature/Epic lifecycle documents remain canonical for lifecycle facts. +- `CON-01` A capsule must be sufficient to choose one next safe action but must not duplicate requirements, decisions, statuses or registries. + +## Design Requirement Decision + +| Decision | Reason | Downstream owner | +| --- | --- | --- | +| `Design required: yes` | The issue explicitly requires choosing frontmatter vs dedicated handoff storage and defines a new persisted file-format contract. | [`design.md`](design.md) | + +## Artifact Routing Decision + +| Artifact | Decision | Trigger / reason | Route / owner | +| --- | --- | --- | --- | +| `design.md` | selected | Storage boundary, schema ownership and lifecycle mapping require solution-space reasoning. | `design.md` | +| `task-capsule.md` | selected | The active feature package needs the same resumable state carrier it defines. | `task-capsule.md` | +| `use-cases/README.md` | omitted | No project-level user scenario changes. | none | + +## Validation Profile Decision + +| Profile | Triggers / rationale | Downgrade approval | +| --- | --- | --- | +| `documentation` | Only governed Markdown/template documentation changes; no executable behavior, runtime contract, config or release path. Apply link, schema/frontmatter, targeted docs checks and semantic read-through. | none | + +## Verify + +### Exit Criteria + +- `EC-01` A reusable schema/example documents every required field and explicit SSoT boundary. +- `EC-02` Feature and Epic paths, field owners, lifecycle updates and resume inputs are explicit and traceable to their canonical flows. +- `EC-03` Registry projection and all out-of-scope runtime work are explicitly bounded. + +### Traceability matrix + +| Requirement ID | Problem refs | Acceptance refs | Checks | Evidence IDs | +| --- | --- | --- | --- | --- | +| `REQ-01` | `CON-01` | `EC-01`, `SC-01` | `CHK-01` | `EVID-01` | +| `REQ-02` | `ASM-01`, `ASM-02` | `EC-02`, `SC-02` | `CHK-02` | `EVID-02` | +| `REQ-03` | `ASM-02` | `EC-02`, `SC-03` | `CHK-02` | `EVID-02` | +| `REQ-04` | `CON-01` | `EC-03`, `SC-04` | `CHK-01`, `CHK-02` | `EVID-01`, `EVID-02` | + +### Acceptance Scenarios + +- `SC-01` A reader can instantiate a capsule and find every required field with a concrete example. +- `SC-02` A reader can identify the Feature and Epic package path and the canonical owner for each field. +- `SC-03` A new session can select the next action from the capsule plus referenced owners and priming inputs, without the prior transcript. +- `SC-04` A registry projection cannot override requirements, lifecycle status or capsule state. + +### Checks + +| Check ID | Covers | How to check | Expected result | Evidence path | +| --- | --- | --- | --- | --- | +| `CHK-01` | `EC-01`, `EC-03`, `SC-01`, `SC-04` | `rg -n` required keys and SSoT/projection rules in `template/memory-bank/flows/task-capsule.md` | All fields and boundaries are present | `artifacts/ft-109/verify/chk-01/` | +| `CHK-02` | `EC-02`, `SC-02`, `SC-03` | Link/schema lint plus semantic read-through of task-capsule, Feature, Epic and session handoff docs | Links resolve and continuation map is consistent | `artifacts/ft-109/verify/chk-02/` | + +### Test matrix + +| Check ID | Evidence IDs | Evidence path | +| --- | --- | --- | +| `CHK-01` | `EVID-01` | `artifacts/ft-109/verify/chk-01/` | +| `CHK-02` | `EVID-02` | `artifacts/ft-109/verify/chk-02/` | + +### Evidence + +- `EVID-01` Required-field and SSoT boundary scan output. +- `EVID-02` Template lint/doctor output and semantic read-through record. + +### Evidence contract + +| Evidence ID | Artifact | Producer | Path contract | Reused by checks | +| --- | --- | --- | --- | --- | +| `EVID-01` | Required-field scan | verify-runner | `artifacts/ft-109/verify/chk-01/` | `CHK-01` | +| `EVID-02` | Documentation validation and read-through | verify-runner / reviewer | `artifacts/ft-109/verify/chk-02/` | `CHK-02` | diff --git a/memory-bank/features/FT-109/design.md b/memory-bank/features/FT-109/design.md new file mode 100644 index 0000000..aad4328 --- /dev/null +++ b/memory-bank/features/FT-109/design.md @@ -0,0 +1,122 @@ +--- +title: "FT-109: Task Capsule Design" +doc_kind: feature +doc_function: canonical +purpose: "Own the selected storage boundary, schema shape and Feature/Epic field ownership for the Task Capsule contract." +derived_from: + - brief.md + - ../../../template/memory-bank/flows/task-capsule.md + - ../../../template/memory-bank/flows/feature.md + - ../../../template/memory-bank/flows/epic.md + - ../../../template/memory-bank/flows/templates/process/session-handoff.md +status: active +audience: humans_and_agents +--- + +# FT-109: Task Capsule Design + +## Design Pack + +| Path | Classification | Ownership | +| --- | --- | --- | +| `design.md` | root | selected storage and ownership facts | +| `../../../template/memory-bank/flows/task-capsule.md` | external-dependency | generic contract and reusable schema | +| `../../../template/memory-bank/flows/templates/process/task-capsule.md` | constituent | instantiation template | + +## Context + +The parent initiative requires durable continuation while existing Feature and +Epic flows already own lifecycle facts. The design must permit a session to +select one safe action without copying those facts into a second active owner. + +## C4 Applicability + +`C4 not required`: this is a documentation contract and does not add runtime +components or deployment topology. The relevant boundary is documented as +artifact ownership and file references. + +## Architecture Coverage Decision + +| Aspect | Decision | Rationale | +| --- | --- | --- | +| Components | covered | Feature/Epic package, canonical owners, capsule and optional registry projection are identified. | +| Connectors | covered | Relative links and immutable evidence refs are the only handoff bindings. | +| Configuration | N/A | No runtime/configuration is introduced. | +| Behavioral semantics | covered | Resume, pause, reroute and closure update rules are defined. | +| Quality/evolution concerns | covered | SSoT, revisions, stale refs and projection-only registry rules are explicit. | + +## Selected Solution + +- `SOL-01` Store one dedicated `task-capsule.md` in each active Feature or Epic package. +- `SOL-02` Keep lifecycle/status/requirements/decisions in existing canonical owners; capsule fields reference owner paths and revisions. +- `SOL-03` Reuse the session-handoff continuation sequence, with a structured schema and one exact `next_action`. +- `SOL-04` Permit a registry/index only as a read/projection view. + +## Alternatives Considered + +| Alternative | Decision | Reason | +| --- | --- | --- | +| `ALT-01` Put full capsule state in owner frontmatter | rejected | Mixes transient resumable state with canonical lifecycle and makes each owner carry a second contract. | +| `ALT-02` Use only a generic session handoff outside packages | rejected | Loses package ownership and makes Feature/Epic location ambiguous. | +| `ALT-03` Dedicated package-local capsule plus owner refs | selected | Keeps durable continuation local, explicit and non-duplicating. | + +## Trade-offs + +- `TRD-01` A session reads the capsule and referenced owners, but the schema is durable and machine-readable without requiring a full transcript. +- `TRD-02` Two package types have two paths, but this preserves the existing Feature/Epic ownership boundary and prevents an umbrella registry from owning slice state. + +## Accepted Local Decisions + +- `SD-01` `task-capsule.md` is the package-local handoff artifact; its frontmatter carries only document metadata and `status`. +- `SD-02` Operational state is a structured body contract; owner documents remain authoritative for lifecycle and requirements. +- `SD-03` Every capsule update leaves exactly one `next_action` and records stale-reference or rejected-handoff diagnostics. + +## Contracts + +- `CTR-01` Schema keys and ownership rules are canonical in `template/memory-bank/flows/task-capsule.md`. +- `CTR-02` Feature storage is `memory-bank/features/FT-XXX/task-capsule.md`; Epic storage is `memory-bank/epics/EP-XXX/task-capsule.md`. +- `CTR-03` Registry entries are projections and cannot be used to resolve conflicts with capsule or canonical owners. + +## Invariants + +- `INV-01` One task has one active capsule and one exact next action. +- `INV-02` A capsule never overrides a canonical owner or silently repairs a stale reference. +- `INV-03` Epic slice state is handed off to a separate routed Feature package. + +## Failure Modes + +- `FM-01` Missing/stale owner ref: pause, re-ground and update the owner or reroute. +- `FM-02` More than one next action: reject handoff and reduce to one sequenced action. +- `FM-03` Registry conflicts with owner: ignore projection and report the canonical owner conflict. + +## Rollout / Backout + +Not applicable to runtime rollout. Revert the documentation change as one Git +revision; downstream packages continue using their existing owner documents. + +## Design Verification + +| Analysis class | Required | Method | Result/evidence | +| --- | --- | --- | --- | +| Contract compatibility | yes | Compare schema and ownership with Feature, Epic and session-handoff flow docs. | `EVID-02` | +| State/transition completeness | yes | Trace bootstrap, gate, handoff, pause, reroute and closure updates. | `EVID-02` | +| Failure propagation | yes | Check stale refs, rejected handoff and registry conflict diagnostics. | `EVID-01` | +| Concurrency/ordering | no | No runtime concurrency; single writer and exact-next-action rule are documented. | N/A rationale in `INV-01` | +| Security boundaries | no | No access or auth behavior changes. | N/A | +| Capacity/latency | no | No runtime path. | N/A | +| Migration/evolution safety | yes | Check owner revisions, package-local paths and projection-only registry rule. | `EVID-02` | + +## External Dependency Readiness + +Existing Feature, Epic and session-handoff documents are active and remain +owners; this design adds links and explicit mapping without changing their +existing lifecycle contracts. + +## Traceability + +| Requirement | Solution refs | Contract/invariant refs | Evidence | +| --- | --- | --- | --- | +| `REQ-01` | `SOL-01`, `SOL-03` | `CTR-01`, `INV-01` | `EVID-01` | +| `REQ-02` | `SOL-01`, `SOL-02` | `CTR-02`, `INV-02` | `EVID-02` | +| `REQ-03` | `SOL-02`, `SOL-03` | `CTR-01`, `INV-03` | `EVID-02` | +| `REQ-04` | `SOL-04` | `CTR-03`, `FM-03` | `EVID-01` | diff --git a/memory-bank/features/FT-109/implementation-plan.md b/memory-bank/features/FT-109/implementation-plan.md new file mode 100644 index 0000000..c67b2f5 --- /dev/null +++ b/memory-bank/features/FT-109/implementation-plan.md @@ -0,0 +1,146 @@ +--- +title: "FT-109: Task Capsule Contract Implementation Plan" +doc_kind: feature +doc_function: derived +purpose: "Derived execution plan for publishing and validating the generic Task Capsule contract." +derived_from: + - brief.md + - design.md + - ../../../template/memory-bank/flows/feature.md + - ../../../template/memory-bank/engineering/testing-policy.md + - ../../ops/development.md +status: archived +audience: humans_and_agents +--- + +# FT-109: Task Capsule Contract Implementation Plan + +## Цель текущего плана + +Publish the generic Task Capsule contract and update the Feature/Epic/session +handoff documentation indexes and lifecycle boundaries without implementing a +runtime or validator. + +## Grounding Evidence + +- `GRND-01` at `8066bed81fa4245d6fd3e380c39312720622b296`: `template/memory-bank/flows/{routing,feature,epic}.md` define route, lifecycle owners and gates; they are the required integration points. +- `GRND-02` at `8066bed81fa4245d6fd3e380c39312720622b296`: `template/memory-bank/flows/templates/process/session-handoff.md` already defines continuation sections; the new capsule must extend, not replace, it. +- `GRND-03` at `8066bed81fa4245d6fd3e380c39312720622b296`: `template/memory-bank/dna/{governance,frontmatter}.md` require active governed docs and upstream ownership; the contract must preserve those rules. +- `GRND-04` at `8066bed81fa4245d6fd3e380c39312720622b296`: `memory-bank/features/README.md` confirms project-local FT packages are the instantiated delivery owners; no existing package conflicts with `FT-109`. + +## Implementation Priming + +| Order | Path | Section / symbol | Grounding | Purpose | Required step | +| --- | --- | --- | --- | --- | --- | +| 1 | `template/memory-bank/flows/task-capsule.md` | whole document | `GRND-01`, `GRND-02`, `GRND-03` | canonical schema, ownership and resume contract | `STEP-01` | +| 2 | `template/memory-bank/flows/templates/process/task-capsule.md` | whole document | `GRND-02`, `GRND-03` | reusable instantiation template | `STEP-01` | +| 3 | `template/memory-bank/flows/{README,feature,epic}.md` | indexes and lifecycle rules | `GRND-01`, `GRND-02` | discoverability and lifecycle mapping | `STEP-02` | +| 4 | `template/memory-bank/flows/templates/process/session-handoff.md` | wrapper notes | `GRND-02` | continuation integration | `STEP-02` | +| 5 | `memory-bank/features/FT-109/{brief,design,task-capsule}.md` | canonical owner package | `GRND-04` | issue traceability and resume example | `STEP-03` | + +## Grounding / Support References + +- Existing references: `template/memory-bank/flows/routing.md`, `feature.md`, `epic.md`, `templates/process/session-handoff.md`. +- Existing validation commands: `ruby tools/validate-priming-manifests.rb template/memory-bank`; `memory-bank-cli lint --scope-root template/memory-bank --entrypoint template/memory-bank/README.md`; `memory-bank-cli doctor --profile template`; `git diff --check`. +- No executable test surface exists; documentation profile requires targeted schema/frontmatter/link checks and semantic read-through. + +## Current State / Reference Points + +The repository is documentation-only, the worktree is clean at terminal +revision `d7496b8`, and the generic template now contains the Task Capsule +contract. `memory-bank/` is the project-local canonical adaptation layer; +`template/memory-bank/` is the generic payload. + +## Test Strategy + +- Run required template structure, priming-manifest, link/reachability, + governance/marker, whitespace and required-key checks. +- Perform semantic read-through of the capsule against Feature, Epic and + session-handoff owners, then run `codex review --uncommitted` for the + repository diff. +- No manual-only gap: the acceptance is documentation-only and all stated + predicates have deterministic file or command evidence. + +## Open Questions / Ambiguities + +`OQ-01 none`: issue scope is sufficient; runtime and validator work are explicit +follow-ups and must not enter this delivery unit. + +## Environment Contract + +- Worktree: `/Users/danil/worktrees/feature/issue-109-define-task-capsule-contract-for-memory` +- Branch: `feature/issue-109-define-task-capsule-contract-for-memory` +- Grounded immutable revision: `8066bed81fa4245d6fd3e380c39312720622b296` +- Required external CI: GitHub checks for [PR #110](https://github.com/dapi/memory-bank/pull/110); terminal check passed at `https://github.com/dapi/memory-bank/actions/runs/31041845661/job/92427832402`. + +## Preconditions + +- `PRE-01` FT-109 brief and design remain active and internally consistent. +- `PRE-02` No parent/linked issue changes the scope or canonical owner. +- `PRE-03` Generic changes remain under `template/memory-bank/`; no project-specific details leak into the template. + +## Design Realization Mapping + +| Realization target | Design refs | Requirement refs | Target step | Check/evidence | +| --- | --- | --- | --- | --- | +| Canonical schema and SSoT boundary | `SOL-01..SOL-04`, `CTR-01`, `INV-01..03` | `REQ-01`, `REQ-04` | `STEP-01` | `CHK-01` / `EVID-01` | +| Feature/Epic lifecycle mapping | `SD-01..03`, `CTR-02` | `REQ-02`, `REQ-03` | `STEP-02` | `CHK-02` / `EVID-02` | +| Reusable package example | `SOL-03` | `REQ-01`, `REQ-03` | `STEP-03` | `CHK-02` / `EVID-02` | + +## Workstreams + +- `WS-01` Publish canonical contract and process template. +- `WS-02` Integrate links and update lifecycle/session handoff mapping. +- `WS-03` Validate, review and freeze evidence. + +## Approval Gates + +None. No runtime, production, security, migration or external-effect action is +within scope. + +## Порядок работ + +| Step ID | Actor | Implements | Goal | Touchpoints | Artifact | Verifies | Evidence IDs | Check command / procedure | Blocked by | Needs approval | Escalate if | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| `STEP-01` | delivery-orchestrator | `REQ-01`, `REQ-04`, `SOL-*`, `CTR-01`, `INV-*` | Publish canonical schema, example and projection boundary | `template/memory-bank/flows/task-capsule.md`, process template | Generic contract | `SC-01`, `SC-04` | `EVID-01` | required-key scan and semantic read-through | `PRE-01` | none | owner conflict | +| `STEP-02` | delivery-orchestrator | `REQ-02`, `REQ-03`, `SD-*`, `CTR-02` | Map Feature/Epic/session handoff lifecycle | flow indexes and lifecycle docs | Updated flow docs | `SC-02`, `SC-03` | `EVID-02` | template lint/doctor and link audit | `STEP-01` | none | scope expands | +| `STEP-03` | delivery-orchestrator | `REQ-01..04` | Freeze FT-109 artifacts and validate candidate | FT-109 package and checks | Reviewable repository diff | `SC-01..04` | `EVID-01`, `EVID-02` | all required commands and review | `STEP-02` | none | failing required check | + +## Parallelizable Work + +- `PAR-01` No parallel writes: all docs share the same contract and one writer lease. + +## Checkpoints + +| Checkpoint ID | Refs | Condition | Evidence IDs | +| --- | --- | --- | --- | +| `CP-01` | `STEP-01` | Canonical schema and ownership are complete | `EVID-01` | +| `CP-02` | `STEP-02` | Feature/Epic/session handoff links and mappings are consistent | `EVID-02` | +| `CP-03` | `STEP-03` | Required checks and clean review complete on frozen candidate | `EVID-01`, `EVID-02` | + +## Execution Risks + +| Risk ID | Risk | Impact | Mitigation | Trigger | +| --- | --- | --- | --- | --- | +| `ER-01` | Capsule wording duplicates lifecycle owners | SSoT violation | Keep owner table and refs explicit; review against governance | Duplicate status/requirements found | +| `ER-02` | Flow mapping accidentally expands into runtime work | Scope breach | Keep runtime/validator as follow-up issues | New executable surface proposed | + +## Stop Conditions / Fallback + +| Stop ID | Related refs | Trigger | Immediate action | Safe fallback state | +| --- | --- | --- | --- | --- | +| `STOP-01` | `DEC-01`, `ER-01` | Conflicting canonical owner or unresolved storage trade-off | Pause and route to owner/human decision | Last clean docs revision | +| `STOP-02` | `ER-02` | Runtime/validator scope appears | Stop mutation and create separate Task Routing handoff | Generic contract only | + +## Plan-local Evidence + +| Evidence ID | Artifact | Producer | Path contract | Reused by checkpoints | +| --- | --- | --- | --- | --- | +| `EVID-09` | Frozen candidate revision and review record | reviewer | Run Ledger / PR review record | `CP-03` | + +## Готово для приемки + +- Generic contract, process template and lifecycle mappings are published. +- FT-109 owners trace every requirement to concrete checks and evidence. +- Required documentation validation, semantic read-through, review, commit, + push, PR and required CI are complete. diff --git a/memory-bank/features/FT-109/review-record.md b/memory-bank/features/FT-109/review-record.md new file mode 100644 index 0000000..97ebe90 --- /dev/null +++ b/memory-bank/features/FT-109/review-record.md @@ -0,0 +1,45 @@ +--- +title: "FT-109: Review Record" +doc_kind: process +doc_function: evidence +purpose: "External carrier for the frozen FT-109 artifact and implementation review verdicts." +derived_from: + - brief.md + - design.md + - implementation-plan.md + - ../../../template/memory-bank/flows/task-capsule.md +status: active +audience: humans_and_agents +--- + +# FT-109: Review Record + +This record is an evidence carrier outside the reviewed Feature owners. It does +not define requirements, lifecycle state or acceptance; those remain owned by +`brief.md`, `design.md` and `implementation-plan.md`. + +## Frozen candidate + +- Candidate: committed documentation delivery at `125566d` (`125566dd45a1c4fae1500f828861dd913f5636df`). +- Owner revisions: `brief.md@sha256:33f3a3a61fbd96fc9483aa269a2b6eb22b361108de3168cecadb86cbb1835f32`, `design.md@sha256:c9f9d0b072a8acaaaa04fb183f0aeb0c942ccd2a537990080537055445135803`, `implementation-plan.md@sha256:fa57c8300eda26152a616626e04e279987bcf0a73cb400fbeddb7ec48107cdbd`. +- Review carrier: Run Ledger state plus the committed `codex review --base develop` output for this candidate. This later evidence-carrier-only update does not change the reviewed owner artifacts. + +## Artifact review + +- Scope: requirements, design, plan and process artifacts against Feature Flow and Task Capsule predicates. +- Command: `codex review --base develop`. +- Verdict: clean after bounded fixes; latest clean verdict is recorded in the Run Ledger before delivery mutation. + +## Implementation review + +- Scope: repository diff against accepted FT-109 owners and the documentation validation profile. +- Command: `codex review --base develop`. +- Verdict: clean after bounded fixes; latest clean verdict is recorded in the Run Ledger before delivery mutation. + +## Reproducible checks + +- `ruby tools/validate-priming-manifests.rb template/memory-bank` — pass. +- `memory-bank-cli lint --scope-root template/memory-bank --entrypoint template/memory-bank/README.md` — pass. +- `memory-bank-cli doctor --profile template` — pass. +- `memory-bank-cli lint --scope-root memory-bank --entrypoint memory-bank/README.md` — pass. +- `git diff --check` — pass. diff --git a/memory-bank/features/FT-109/task-capsule.md b/memory-bank/features/FT-109/task-capsule.md new file mode 100644 index 0000000..0402a29 --- /dev/null +++ b/memory-bank/features/FT-109/task-capsule.md @@ -0,0 +1,79 @@ +--- +title: "FT-109: Task Capsule" +doc_kind: process +doc_function: canonical +purpose: "Active resumable state for the FT-109 Task Capsule contract delivery unit." +derived_from: + - ../../../template/memory-bank/flows/task-capsule.md + - brief.md +status: archived +audience: humans_and_agents +--- + +# FT-109: Task Capsule + +```yaml +task_id: FT-109 +route: {name: Feature, revision: 1, source_ref: ../../../template/memory-bank/flows/routing.md} +stage: {current: Done, canonical_owner: brief.md} +current_role: delivery-orchestrator +next_role: none +artifact_refs: + - {path: brief.md, owner: feature-brief, revision: sha256:33f3a3a61fbd96fc9483aa269a2b6eb22b361108de3168cecadb86cbb1835f32} + - {path: design.md, owner: feature-design, revision: sha256:c9f9d0b072a8acaaaa04fb183f0aeb0c942ccd2a537990080537055445135803} + - {path: implementation-plan.md, owner: feature-plan, revision: sha256:fa57c8300eda26152a616626e04e279987bcf0a73cb400fbeddb7ec48107cdbd} +completed_action: {id: STEP-03, summary: "Completed final documentation validation and implementation review", evidence_refs: [EVID-FINAL]} +current_action: {id: CLOSE-01, summary: "Verified terminal Feature package and delivery references", evidence_refs: [EVID-CI]} +next_action: {owner: none, id: DONE-01, summary: "No further action; package is archived and issue is closed", stop_condition: "Terminal state reached"} +assumptions: + - {id: ASM-01, summary: "Generic rules belong in template/memory-bank", owner_ref: brief.md} + - {id: ASM-02, summary: "Existing Feature/Epic documents remain lifecycle owners", owner_ref: design.md} +risks: + - {id: ER-01, summary: "Downstream adoption may require separate follow-up issues", owner_ref: implementation-plan.md} +evidence: + - {id: EVID-BOOTSTRAP, ref: "memory-bank/features/FT-109/brief.md@sha256:33f3a3a61fbd96fc9483aa269a2b6eb22b361108de3168cecadb86cbb1835f32; design.md@sha256:c9f9d0b072a8acaaaa04fb183f0aeb0c942ccd2a537990080537055445135803", proves: "Problem and selected solution owners exist"} + - {id: EVID-PLAN-READY, ref: "review-record.md#artifact-review", proves: "Draft Plan Ready artifact review passed"} + - {id: EVID-FINAL, ref: "review-record.md#implementation-review", proves: "Final documentation candidate passed validation and review"} + - {id: EVID-CI, ref: "https://github.com/dapi/memory-bank/actions/runs/31041845661/job/92427832402", proves: "Required PR CI passed for the terminal repository revision"} +stop_conditions: + - {id: STOP-01, trigger: "Canonical owner conflict or route expansion", action: "Pause mutations and reroute"} +last_handoff_diagnostic: {status: none, reason_code: none, message: none, repair_action: none, evidence_ref: none} +updated_at: 2026-08-06T02:45:00+03:00 +``` + +Resume by reading this capsule, the referenced FT-109 owners, the Feature Flow +Plan Ready inputs and only the evidence needed by `next_action`. The capsule +does not override any owner or replace the Run Ledger. + +## Continuation Priming Inputs + +Read the Feature Flow `plan_ready` and `execution_continuation` source sets +before resuming; verify the referenced owner revisions first. The exact source +manifests and last verified revisions for this handoff are: + +- `template/memory-bank/flows/priming/feature.yaml@sha256:df12e045f0d624eaa7e82cd5cd0ca5ff23732eb96d8f77e63fae932f35f8b7f6` + (`plan_ready` and `execution_continuation`). +- `template/memory-bank/flows/priming/process.yaml@sha256:9a6be526824cbcff2caf58c2ff1517a6984eff3f2874d9de840b20400f8f4834` + (`process_documentation`). +- Last verified owner revisions: `brief.md@sha256:33f3a3a61fbd96fc9483aa269a2b6eb22b361108de3168cecadb86cbb1835f32`, + `design.md@sha256:c9f9d0b072a8acaaaa04fb183f0aeb0c942ccd2a537990080537055445135803`, + `implementation-plan.md@sha256:fa57c8300eda26152a616626e04e279987bcf0a73cb400fbeddb7ec48107cdbd`. + +## Human-readable Handoff + +### Current State + +- Completed: final documentation validation and implementation review passed. +- Current: terminal Feature package and delivery references verified. + +### Assumptions and Open Risks + +- Assumptions and risks remain linked to `brief.md`, `design.md` and the plan. + +### Next Checks + +- No further checks; terminal state reached. + +### Handoff Diagnostic + +- `none` until the first role handoff is accepted, rejected or blocked. diff --git a/memory-bank/features/README.md b/memory-bank/features/README.md index b1aee59..ccd8f02 100644 --- a/memory-bank/features/README.md +++ b/memory-bank/features/README.md @@ -28,6 +28,10 @@ audience: humans_and_agents ## Naming +## Active Packages + +- [`FT-109/`](FT-109/README.md) — Task Capsule contract delivery package. + - Базовый формат: `FT-XXX/` - Вместо `XXX` используй идентификатор, принятый в проекте: issue id, ticket id или другой стабильный ключ - Один package = одна delivery-единица diff --git a/template/memory-bank/flows/README.md b/template/memory-bank/flows/README.md index 1b41539..52b6934 100644 --- a/template/memory-bank/flows/README.md +++ b/template/memory-bank/flows/README.md @@ -35,5 +35,6 @@ audience: humans_and_agents - [Epic Flow](epic.md) — Epic Intake/Proposal, lifecycle крупных инициатив, roadmap, decision log, risks и handoff в feature packages. - [Use Case Flow](use-case.md) — критерии, lifecycle и ownership для project-level `UC-*`, включая operational / agentic сценарии. - [Feature Flow](feature.md) — lifecycle `brief.md -> optional design.md -> implementation-plan.md`, gates и стабильные ID (`REQ-*`, `SOL-*`, `STEP-*`). +- [Task Capsule Contract](task-capsule.md) — package-local resumable state, field ownership, lifecycle mapping and projection-only registry boundary. - [Feature Artifact Catalog](feature-artifact-catalog.md) — optional problem/solution/execution artifacts, selection triggers, ownership, default forms и template availability. - [Templates Index](templates/README.md) — эталонные шаблоны governed-документов, включая PRD, use case, epic, feature и ADR. diff --git a/template/memory-bank/flows/epic.md b/template/memory-bank/flows/epic.md index 2f5a72b..beb7fb6 100644 --- a/template/memory-bank/flows/epic.md +++ b/template/memory-bank/flows/epic.md @@ -57,9 +57,14 @@ Intake facts и open questions принадлежат `brief.md`; при пря 6. `decision-log.md` - local decision ledger for decisions that affect the epic but do not require global ADR. 7. `subissues.md` - registry of candidate and accepted delivery subissues, each mapped to roadmap waves and source `SLICE-*`/`UC-*`. 8. `risks.md` - epic-level risk register for financial, operational, scope and delivery risks. -9. `design.md`, `specs/**`, `diagrams/**`, `source-docs/**` — опциональные knowledge-артефакты. Они допустимы только когда индексируются из epic package и подчиняются правилам knowledge-артефактов ниже. -10. `implementation-plan.md` не создаётся внутри epic. Code-level execution belongs to a separate `memory-bank/features/FT-/` package. -11. Для epic package используй templates from `memory-bank/flows/templates/epic/`. +9. An active Epic may carry `task-capsule.md` beside `README.md`, `brief.md` and + `charter.md`. It stores only resumable epic-level state and refs; lifecycle, + roadmap, risk and subissue facts remain with their canonical owners. After + `Roadmap Ready`, each accepted slice receives a separate issue, Task Routing, + Feature package and Feature capsule. +10. `design.md`, `specs/**`, `diagrams/**`, `source-docs/**` — опциональные knowledge-артефакты. Они допустимы только когда индексируются из epic package и подчиняются правилам knowledge-артефактов ниже. +11. `implementation-plan.md` не создаётся внутри epic. Code-level execution belongs to a separate `memory-bank/features/FT-/` package. +12. Для epic package используй templates from `memory-bank/flows/templates/epic/`. ## Layer Model @@ -186,6 +191,7 @@ flowchart LR - [ ] фактический outcome сопоставлен с `charter.md` acceptance и записан в его `Outcome`/`Acceptance` - [ ] `roadmap.md`, `subissues.md` и `risks.md` отражают финальное состояние; `decision-log.md`, если используется, также отражает финальное состояние - [ ] открытые риски и follow-up work имеют owner и отдельные task references +- [ ] если Epic adopted `task-capsule.md`, он содержит финальные owner/evidence refs и не копирует state отдельных Feature slices - [ ] человек подтвердил закрытие инициативы - [ ] package `README.md` имеет `epic_stage: done`; для отменённой инициативы используется `epic_stage: cancelled` diff --git a/template/memory-bank/flows/feature-artifact-catalog.md b/template/memory-bank/flows/feature-artifact-catalog.md index 40c42c9..7802692 100644 --- a/template/memory-bank/flows/feature-artifact-catalog.md +++ b/template/memory-bank/flows/feature-artifact-catalog.md @@ -35,6 +35,7 @@ audience: humans_and_agents | Project-level `UC-*` | Какой устойчивый пользовательский / операторский сценарий поддерживает система? | Scenario повторяется во времени или используется несколькими features | `memory-bank/use-cases/UC-XXX.md` | Canonical reusable scenario | [Use Case](templates/use-case/UC-XXX.md) | | Epic package | Как координируются roadmap, risks и несколько delivery units? | Работа крупнее одной vertical feature | `memory-bank/epics/EP-XXX/` | Initiative coordination, не feature execution | [Epic](templates/epic/README.md) | | `README.md` | Какие artifacts реально входят в feature package и в каком порядке их читать? | Любой feature package | `features/FT-XXX/README.md` | Routing only | [Feature README](templates/feature/README.md) | +| `task-capsule.md` | Как продолжить активную задачу между sessions, machines или roles без полного transcript? | Работа пересекает session/machine/role boundary или требует persisted handoff | `features/FT-XXX/task-capsule.md` или `epics/EP-XXX/task-capsule.md` | Structured continuation state; canonical requirements, solution and lifecycle remain with their owners | [Task Capsule](templates/process/task-capsule.md) | | `brief.md` | Какую проблему решаем, что входит в scope и как принимаем результат? | Любой feature package | `features/FT-XXX/brief.md` | Canonical problem, requirements, acceptance and evidence contract | [Brief](templates/feature/brief.md) | | Feature-local use cases | Какие happy, edge и error journeys удобнее review отдельно? | Много scenarios/roles или нужен `FUC -> REQ -> CHK` mapping | `use-cases/README.md` | Derived scenario projection; canonical acceptance остается в `brief.md` | [Feature Use Cases](templates/feature/support/use-cases.md) | | Runtime surface inventory | Где behavior существует сейчас и какой context доступен? | Несколько entrypoints, mappings, fallbacks или context variants | `runtime-surfaces.md` | Current-state reference | [Runtime Surfaces](templates/feature/support/runtime-surfaces.md) | diff --git a/template/memory-bank/flows/feature.md b/template/memory-bank/flows/feature.md index 5b82605..4755887 100644 --- a/template/memory-bank/flows/feature.md +++ b/template/memory-bank/flows/feature.md @@ -74,6 +74,7 @@ immutable revision и `GRND-*` evidence. 16. Полное чтение PRD corpus не создаёт semantic dependency от каждого PRD. `brief.md: derived_from` импортирует только фактические upstream-owner references и не копирует весь upstream scope. 17. Если работа крупнее одной delivery-feature и требует общего roadmap, cross-feature risk register или нескольких delivery units, не расширяй feature package: повтори [`Task Routing`](routing.md), выбери [`Epic Flow`](epic.md) и после epic handoff веди каждую утвержденную delivery-единицу как отдельный feature package. 18. Validation profile выбирается в `brief.md` по [`validation-profiles.md`](../engineering/validation-profiles.md). `design.md` может уточнить risk facts, а `implementation-plan.md` разворачивает minimum contract в команды, suites и checkpoints, но ни один из них не дублирует profile decision. +19. If a Feature task must cross a session, machine or role boundary, it must instantiate `task-capsule.md` beside `brief.md`; compact work completed within one governed session may omit it. The capsule references `brief.md`, the design pack and `implementation-plan.md`; it does not own requirements, acceptance, lifecycle status, selected design or execution sequencing. Use the canonical [Task Capsule Contract](task-capsule.md) for schema and update rules. ## Feature Package Anatomy @@ -330,6 +331,14 @@ Plan Ready artifact-review convergence допускает не более пят - [ ] `brief.md` → `delivery_status: done` - [ ] `implementation-plan.md` → `status: archived` +When a package adopts a Task Capsule for cross-session or handoff state, update +it at every gate, writer handoff, checkpoint, review/CI result, pause, reroute +and closure with the accepted stage, immutable artifact refs, evidence, one +exact next action and any handoff diagnostic. Packages that do not adopt a +capsule follow the ordinary Feature Flow owner documents and handoff rules. +A Feature capsule is sufficient to select the next safe action, but the +referenced canonical owners remain required for execution and verification. + ### → Cancelled (из любой стадии после Draft Feature) - [ ] `brief.md` → `delivery_status: cancelled` diff --git a/template/memory-bank/flows/priming/process.yaml b/template/memory-bank/flows/priming/process.yaml index d04f6ee..66e9503 100644 --- a/template/memory-bank/flows/priming/process.yaml +++ b/template/memory-bank/flows/priming/process.yaml @@ -5,6 +5,7 @@ stages: - memory-bank/flows/templates/process/process-card.md - memory-bank/flows/templates/process/lifecycle-protocol.md - memory-bank/flows/templates/process/session-handoff.md + - memory-bank/flows/templates/process/task-capsule.md - memory-bank/flows/templates/process/priming.yaml - memory-bank/dna/governance.md - memory-bank/dna/lifecycle.md diff --git a/template/memory-bank/flows/task-capsule.md b/template/memory-bank/flows/task-capsule.md new file mode 100644 index 0000000..0abccec --- /dev/null +++ b/template/memory-bank/flows/task-capsule.md @@ -0,0 +1,217 @@ +--- +title: Task Capsule Contract +doc_kind: governance +doc_function: canonical +purpose: Persist the minimum active-task state needed for safe continuation across sessions, machines, or agents without making the capsule a second source of truth. +derived_from: + - ../dna/governance.md + - ../dna/frontmatter.md + - routing.md + - feature.md + - epic.md + - templates/process/session-handoff.md +canonical_for: + - task_capsule_schema + - task_capsule_storage + - task_capsule_field_ownership + - task_capsule_resume_contract +status: active +audience: humans_and_agents +--- + +# Task Capsule Contract + +Task Capsule — это package-local persisted handoff для одной активной задачи. +Он отвечает на вопрос «что безопасно сделать дальше», но не становится +владельцем требований, solution decisions, lifecycle status или roadmap. + +Adoption is required when a task must survive a session/machine/role boundary +or use a persisted handoff. A compact task that completes within one governed +session may follow its flow without creating a capsule; in that case the flow's +ordinary owner documents and handoff rules remain sufficient. + +## Storage and SSoT boundary + +Храни капсулу как отдельный `task-capsule.md` в package, который владеет +текущей delivery unit: + +| Package | Capsule path | Canonical owners referenced by the capsule | +| --- | --- | --- | +| Feature | `memory-bank/features/FT-XXX/task-capsule.md` | `brief.md`, optional `design.md`/design pack, optional `implementation-plan.md` after Plan Ready, ADRs and evidence carriers | +| Epic | `memory-bank/epics/EP-XXX/task-capsule.md` | `README.md`, `brief.md`/`charter.md`, `roadmap.md`, `risks.md`, `subissues.md` and evidence carriers | + +Epic capsule governs only the epic-level stage and its handoff to a routed +delivery slice. After `Roadmap Ready`, each accepted slice gets its own issue, +Task Routing, Feature package and Feature capsule. The Epic capsule must not +become a registry of feature lifecycle state. + +The capsule uses a minimal combination of persisted state and references: + +- canonical owners retain requirements, scope, acceptance, decisions, + lifecycle statuses, roadmap, risks and implementation sequencing; +- the capsule retains the current resumable checkpoint, references to those + owners, the single next action, evidence and handoff diagnostics; +- a task registry or index may project `task_id`, package path, stage and + capsule status, but never writes or overrides capsule or owner fields; +- a completed handoff archives the capsule with the package, or removes it only + under the package's archival policy. It does not rewrite historical owner + documents. + +## Schema + +An instantiated capsule has YAML frontmatter limited to document identity and +publication status. The operational contract below is the body of the file. +Values are concrete refs or explicit `none`; do not use prose that requires the +next session to reconstruct hidden context. + +```yaml +task_id: "FT-XXX | EP-XXX" +route: + name: "Feature | Epic | ..." + revision: 1 + source_ref: "../../flows/routing.md" +stage: + current: "Plan Ready" + canonical_owner: "brief.md" +current_role: "delivery-owner" +next_role: "reviewer" +artifact_refs: + - path: "brief.md" + owner: "feature-brief" + revision: "" + - path: "implementation-plan.md" + owner: "feature-plan" + revision: "" +completed_action: + id: "STEP-01" + summary: "" + evidence_refs: ["EVID-01"] +current_action: + id: "CP-01" + summary: "" +next_action: + owner: "" + id: "STEP-02 | GATE-02" + summary: "" + stop_condition: "" +assumptions: + - id: "ASM-01" + summary: "" + owner_ref: "brief.md" +risks: + - id: "ER-01" + summary: "" + owner_ref: "implementation-plan.md | risks.md" +evidence: + - id: "EVID-01" + ref: "" + proves: "" +stop_conditions: + - id: "STOP-01" + trigger: "" + action: "" +last_handoff_diagnostic: + status: "accepted | rejected | blocked | none" + reason_code: "" + message: "" + repair_action: "" + evidence_ref: "" +updated_at: "" +``` + +`stage.current` and `canonical_owner` are references to lifecycle facts; they +do not override those owners. `current_action` is the in-flight checkpoint, +while `next_action` is always exactly one action. If work is paused, keep the +last completed action and change only the current/next action and diagnostic. + +## Field ownership and update rules + +| Field | Direct owner | Update rule | +| --- | --- | --- | +| `task_id`, `route` | Task Routing / package README | Set at routing; update only after rerouting with a new route revision. | +| `stage.current`, `stage.canonical_owner` | Feature Flow or Epic Flow owner | Mirror the latest accepted lifecycle gate; never invent a stage in the capsule. | +| `current_role`, `next_role` | Active workflow handoff | Set by the current gate/role; a role may update its own handoff only within the allowed transition. | +| `artifact_refs` | Current package owner | Replace refs when the canonical artifact revision changes; each ref must identify owner and revision. | +| `completed_action`, `current_action`, `next_action` | Current writer / handoff owner | Write atomically at checkpoint; exactly one `next_action` must remain. | +| `assumptions` | Problem/design/plan owner | Add or resolve through the canonical owner first, then refresh the capsule ref. | +| `risks` | Feature `brief.md`/plan or Epic `risks.md` | Track only active risks and point to their owner; do not duplicate the risk register. | +| `evidence` | Producer of the evidence | Add immutable carrier refs and the predicate each proves. | +| `stop_conditions` | Current flow owner | Derive from flow gates, plan and autonomy boundaries; a triggered condition blocks continuation. | +| `last_handoff_diagnostic` | Handoff validator or receiving role | Set on every accepted/rejected/blocked handoff; rejected diagnostics must include `repair_action`. | +| `updated_at` | Capsule writer | Update on every capsule mutation; it has no lifecycle meaning. | + +For Feature packages, `brief.md` owns problem, scope, non-scope, assumptions, +validation profile and acceptance; `design.md` owns selected solution and +contracts when required; `implementation-plan.md` owns execution sequencing. +For Epic packages, `brief.md` owns proposal facts, `charter.md` owns accepted +initiative scope, `roadmap.md` owns waves and handoff gates, `risks.md` owns +cross-feature risks, and `subissues.md` owns the projection of slices. + +## Lifecycle mapping + +Update the capsule at bootstrap, every accepted gate, writer handoff, +checkpoint, review/CI result, reroute, pause and closure. The minimum mapping +is: + +| Lifecycle point | Feature capsule | Epic capsule | +| --- | --- | --- | +| Problem/Proposal Ready | refs active brief and its verify/proposal evidence | refs active proposal `brief.md` and decision owner | +| Solution/Epic Ready | refs active design pack and solution gate evidence | refs active charter and epic readiness evidence | +| Plan/Roadmap Ready | refs active implementation plan and plan-review evidence | refs roadmap, risks and subissues; next action is a separate Task Routing handoff | +| Execution | refs current plan checkpoint, changed artifacts and test evidence | tracks only epic coordination; each slice continues in its own Feature capsule | +| Done/closed | final evidence, handoff diagnostic and archive disposition | accepted subissues and epic closure evidence; no slice details copied | + +On reroute, stop the current writer, record the handback and invalidated refs, +then update the route owner before changing the capsule route. On a human gate, +set one exact request, responsible owner, resume condition and next action. + +## Resume contract + +A new session reads, in order: + +1. the package `task-capsule.md`; +2. the `artifact_refs` at their recorded revisions; +3. the selected flow and its priming inputs for `stage.current`; +4. only the evidence and canonical owner sections needed by `next_action`. + +It verifies the route, owner revisions, worktree/branch and stop conditions +before writing. If any reference is stale, missing or contradicts its owner, +the session pauses and repairs the owner or reroutes; it must not infer the +missing state from the previous transcript. The capsule is sufficient to select +the next safe action, while canonical owners remain necessary to execute and +verify it. + +## Example + +```yaml +--- +title: "FT/EP-XXX: Task Capsule" +doc_kind: process +doc_function: canonical +purpose: "Resume state for the active Feature or Epic delivery unit." +derived_from: + - ../../flows/task-capsule.md + - brief.md +status: active +audience: humans_and_agents +--- + +task_id: "FT-XXX | EP-XXX" +route: {name: Feature, revision: 1, source_ref: ../../flows/routing.md} +stage: {current: Execution, canonical_owner: brief.md} +current_role: delivery-owner +next_role: reviewer +artifact_refs: + - {path: brief.md, owner: feature-brief, revision: } + - {path: design.md, owner: feature-design, revision: } + - {path: implementation-plan.md, owner: feature-plan, revision: } +completed_action: {id: STEP-01, summary: "Updated capsule contract", evidence_refs: [EVID-01]} +current_action: {id: CP-01, summary: "Run template validation"} +next_action: {owner: delivery-owner, id: CHK-01, summary: "Run required checks", stop_condition: "Any required check fails"} +assumptions: [{id: ASM-01, summary: "Registry remains projection-only", owner_ref: brief.md}] +risks: [{id: ER-01, summary: "Downstream adoption may need a separate issue", owner_ref: implementation-plan.md}] +evidence: [{id: EVID-01, ref: "template/memory-bank/flows/task-capsule.md", proves: "Schema and ownership are documented"}] +stop_conditions: [{id: STOP-01, trigger: "Owner revision diverges", action: "Pause and re-ground"}] +last_handoff_diagnostic: {status: none, reason_code: none, message: none, repair_action: none, evidence_ref: none} +updated_at: 2026-08-05T00:00:00Z +``` diff --git a/template/memory-bank/flows/templates/README.md b/template/memory-bank/flows/templates/README.md index 83e0860..ef4d845 100644 --- a/template/memory-bank/flows/templates/README.md +++ b/template/memory-bank/flows/templates/README.md @@ -35,6 +35,7 @@ derived_from: - process/README.md - process/process-card.md - process/session-handoff.md + - process/task-capsule.md - process/lifecycle-protocol.md status: active audience: humans_and_agents @@ -75,4 +76,5 @@ audience: humans_and_agents - [PROC-XXX: Process Documentation Index](process/README.md) — шаблон индекса процесс-документов. Отвечает на вопрос: как собрать routing-layer для reusable process cards, session handoff и lifecycle protocol. - [PROC-XXX: Compact Process Card](process/process-card.md) — шаблон короткого reusable workflow. Отвечает на вопрос: как зафиксировать процесс с одним trigger, шагами и exit criteria. - [PROC-XXX: Session Handoff](process/session-handoff.md) — шаблон передачи состояния между сессиями. Отвечает на вопрос: как продолжить процесс без потери assumptions, risks и next checks. +- [FT/EP-XXX: Task Capsule](process/task-capsule.md) — package-local structured state для продолжения активной Feature или Epic без второго SSoT. - [PROC-XXX: Lifecycle Protocol](process/lifecycle-protocol.md) — шаблон полного lifecycle protocol. Отвечает на вопрос: как вести multi-phase process с gates, verification и rollback. diff --git a/template/memory-bank/flows/templates/epic/package-README.md b/template/memory-bank/flows/templates/epic/package-README.md index 9a3fb1d..910cdeb 100644 --- a/template/memory-bank/flows/templates/epic/package-README.md +++ b/template/memory-bank/flows/templates/epic/package-README.md @@ -52,6 +52,10 @@ audience: humans_and_agents Добавляй `charter.md`, `roadmap.md`, `subissues.md`, `risks.md`, optional `decision-log.md` и knowledge artifacts только когда они реально созданы. Для каждой ссылки кратко укажи, какими facts владеет документ. +Если Epic пересекает session, machine или role boundary, добавь optional +`task-capsule.md` в этот annotated index; он хранит только epic-level +continuation state и не индексирует lifecycle отдельных Feature slices. + ## Handoff До `Roadmap Ready -> Execution` не создавай delivery `FT-*` packages из этого epic. Следуй gates в `memory-bank/flows/epic.md`. diff --git a/template/memory-bank/flows/templates/feature/README.md b/template/memory-bank/flows/templates/feature/README.md index c86571f..f23fc2f 100644 --- a/template/memory-bank/flows/templates/feature/README.md +++ b/template/memory-bank/flows/templates/feature/README.md @@ -79,4 +79,8 @@ audience: humans_and_agents Отвечает на вопрос: где находятся problem space, validation profile decision, canonical verify contract и stable IDs для этой фичи. После появления downstream-документов добавь сюда только существующие routes. Возможный состав и triggers смотри в `memory-bank/flows/feature-artifact-catalog.md`; отсутствие optional use cases, contracts, diagrams, support docs или ADR является нормальным. + +Если Feature пересекает session, machine или role boundary, добавь +`task-capsule.md` в этот annotated index; capsule может появиться до +`implementation-plan.md` и не заменяет canonical `brief.md`. ``` diff --git a/template/memory-bank/flows/templates/process/README.md b/template/memory-bank/flows/templates/process/README.md index 40f9ce4..d675640 100644 --- a/template/memory-bank/flows/templates/process/README.md +++ b/template/memory-bank/flows/templates/process/README.md @@ -76,6 +76,11 @@ audience: humans_and_agents Читать, когда работа переносится между сессиями или компьютерами и нужно сохранить current state, assumptions, risks и next checks. Отвечает на вопрос: как безопасно продолжить уже начатый процесс без потери контекста. +- [`task-capsule.md`](task-capsule.md) + Читать, когда активная Feature или Epic должна сохранить structured state, + owner refs и один exact `next_action` между session, machine или role boundary. + Отвечает на вопрос: как продолжить package-local delivery без второго SSoT. + - [`lifecycle-protocol.md`](lifecycle-protocol.md) Читать, когда процесс состоит из фаз, human gates, verification и rollback и должен переживать длинный delivery-cycle. Отвечает на вопрос: как управлять полным жизненным циклом изменения от старта до handoff или closure. diff --git a/template/memory-bank/flows/templates/process/session-handoff.md b/template/memory-bank/flows/templates/process/session-handoff.md index deda354..8195147 100644 --- a/template/memory-bank/flows/templates/process/session-handoff.md +++ b/template/memory-bank/flows/templates/process/session-handoff.md @@ -26,6 +26,12 @@ canonical_for: Ключевая идея: в handoff попадают не все детали подряд, а только то, что реально нужно для безопасного продолжения. +Для активной Feature или Epic package этот handoff инстанцируется как +package-local [`task-capsule.md`](../../task-capsule.md). Capsule должна +содержать continuation priming inputs и human-readable sections ниже, а также +structured state, owner refs и ровно один `next_action`; отдельный session +handoff нужен только если flow явно назначает другой canonical artifact. + Обязательно фиксируй: - текущий выполненный шаг; diff --git a/template/memory-bank/flows/templates/process/task-capsule.md b/template/memory-bank/flows/templates/process/task-capsule.md new file mode 100644 index 0000000..bfca6fe --- /dev/null +++ b/template/memory-bank/flows/templates/process/task-capsule.md @@ -0,0 +1,83 @@ +--- +title: "FT/EP-XXX: Task Capsule" +doc_kind: process +doc_function: template +purpose: "Instantiable package-local Task Capsule for resumable active-task state." +derived_from: + - ../../task-capsule.md + - ../../../dna/frontmatter.md +status: active +audience: humans_and_agents +template_for: process +template_target_path: ../../../features/FT-XXX/task-capsule.md +template_alternate_target_path: ../../../epics/EP-XXX/task-capsule.md +canonical_for: + - process_template_task_capsule +--- + +# FT/EP-XXX: Task Capsule + +Copy the embedded contract below into the owning Feature or Epic package. Keep +canonical requirements, solution, lifecycle and roadmap facts in their owners; +this document stores only resumable state and references. + +## Instantiated Frontmatter + +```yaml +--- +title: "FT-XXX: Task Capsule" +doc_kind: process +doc_function: canonical +purpose: "Resumable state for the active Feature or Epic package task." +derived_from: + - ../../flows/task-capsule.md + - ../../dna/frontmatter.md +status: active +audience: humans_and_agents +--- +``` + +```yaml +task_id: "FT-XXX | EP-XXX" +route: {name: "Feature | Epic", revision: 1, source_ref: "../../flows/routing.md"} +stage: {current: "", canonical_owner: ""} +current_role: "" +next_role: "" +artifact_refs: [] +completed_action: {id: "", summary: "", evidence_refs: []} +current_action: {id: "", summary: ""} +next_action: {owner: "", id: "", summary: "", stop_condition: ""} +assumptions: [] +risks: [] +evidence: [] +stop_conditions: [] +last_handoff_diagnostic: {status: none, reason_code: none, message: none, repair_action: none, evidence_ref: none} +updated_at: "" +``` + +Before resuming, read this capsule, referenced canonical owners, the selected +flow's priming inputs and the evidence needed for `next_action`. If a reference +is stale or contradictory, stop and repair/reroute before mutation. + +## Continuation Priming Inputs + +Read the owning flow's continuation source set before resuming. Record the exact +manifest or stable source and the last verified owner revision here. + +## Human-readable Handoff + +### Current State + +- Completed action, current checkpoint and current canonical owner. + +### Assumptions and Open Risks + +- Link each active assumption and risk to its canonical owner. + +### Next Checks + +- Keep the checks needed before `next_action` can safely continue. + +### Handoff Diagnostic + +- Record accepted, rejected or blocked handoff status and the repair action.