106 lines
7.5 KiB
Markdown
106 lines
7.5 KiB
Markdown
# Multi-dimensional Roadmap state
|
|
|
|
Use this pattern when an Idea/Epic/Feature Roadmap must combine approval evidence, solution state, and the unified delivery status without conflating them.
|
|
|
|
## Preserve orthogonal authority
|
|
|
|
Do not rename or overwrite one domain's state with another domain's state. Render the dimensions separately:
|
|
|
|
| Dimension | Owner | Example states |
|
|
|---|---|---|
|
|
| Approval gate | Scope | proposed/unapproved, `Approved for Solution`, rejected/deferred decision history |
|
|
| Solution | Architecture | `Incomplete`, `Complete` |
|
|
| Implementation approval | Architecture | `Approved for Implementation`, `Not verified` |
|
|
| Unified delivery | Scope roll-up + Kanban/Delivery/Releases evidence | Product: `IN_BACKLOG`, `IN_DESIGN`, `IN_DELIVERY`, `TO_BE_RELEASED`, `DONE`; Task: `IN_BACKLOG`, `IN_PROGRESS`, `TO_BE_RELEASED`, `DONE` |
|
|
|
|
`Approved for Solution` remains immutable gate evidence after solutioning. It is not a delivery status. A Roadmap that shows only the gate is incomplete, not evidence that work is blocked or delivered.
|
|
|
|
## Fail-closed publication fields
|
|
|
|
The browser adapter must consume verifier-derived fields, not raw approval-shaped YAML. Publish a boolean such as `implementation_approval_verified` only after the build-time verifier binds the exact item, state, actor/authority, UTC decision time, evidence, conditions, immutable history, and baseline. Mutation-test the decision hash/evidence/actor so the public field becomes false.
|
|
|
|
Continue to consume only verifier-admitted exact Task status and validated required-child relationships for unified delivery roll-up.
|
|
|
|
## Aggregate delivery
|
|
|
|
An Idea, Epic, or Feature displays a required-child roll-up without inventing an exact parent transition:
|
|
|
|
1. Validate one direct roll-up set: Idea → resulting Epics/Features, Epic → required Features, Feature → required Tasks. Do not count an Epic and its descendant Feature for the same Idea outcome.
|
|
2. Preserve exact Task states and direct no-child decisions with `status_source: EXACT`; mark every product roll-up `status_source: DERIVED`.
|
|
3. Evaluate required children in this order:
|
|
- all non-empty children `DONE` → parent `DONE`;
|
|
- otherwise all children in `{TO_BE_RELEASED, DONE}` with at least one `TO_BE_RELEASED` → parent `TO_BE_RELEASED`;
|
|
- otherwise any descendant in active or later execution → parent `IN_DELIVERY`;
|
|
- otherwise actively scoped/solutioned → parent `IN_DESIGN`;
|
|
- otherwise parent `IN_BACKLOG`.
|
|
4. Never derive `CANCELLED`. Exclude a cancelled child only after an explicit Scope decision updates the required set.
|
|
5. Keep the internal `status_source` typed, but never expose `DERIVED`, `EXACT`, or `(derived)` as reader status text. Render the canonical uppercase status unchanged and a separate **Status basis** value: `Required-child roll-up` or `Exact item evidence`.
|
|
|
|
Never infer delivery from approval alone. Never let unverified raw Task state or an incomplete child set influence an aggregate.
|
|
|
|
### Status-basis parity probe
|
|
|
|
Roadmap and Board/Focus often render through different label paths: Roadmap may read `executionState`, while lane views read `flowState`. Probe both paths after loading, validating, and publishing the real canonical database:
|
|
|
|
1. Build Roadmap, Board, and Focus from the same public database.
|
|
2. Select one aggregate Epic, one aggregate Feature, and one exact task.
|
|
3. Assert the Epic and Feature expose the expected canonical state plus `Required-child roll-up` in rows, nodes, and accessible labels.
|
|
4. Assert the exact Task exposes the expected canonical state plus `Exact item evidence`.
|
|
5. Assert reader text contains no `(derived)`, `DERIVED`, or `EXACT` status labels while internal source flags remain correct.
|
|
|
|
Checking state equality alone is insufficient: `IN_DELIVERY` can be correct while its status basis is missing or misleading.
|
|
|
|
## Epic solution and implementation summaries
|
|
|
|
For an active Epic:
|
|
|
|
- report solution complete only when every active child Feature has a complete canonical solution package;
|
|
- report implementation readiness as an aggregate such as `All active Features Approved for Implementation` only when every child Feature's implementation decision verifies;
|
|
- do not fabricate an Epic-level Architecture decision when only Feature decisions exist.
|
|
|
|
## Presentation contract
|
|
|
|
Each Roadmap node and same-adapter semantic row should expose:
|
|
|
|
- approval gate;
|
|
- solution status;
|
|
- implementation approval;
|
|
- canonical unified delivery status and separate plain-language Status basis.
|
|
|
|
Explain the dimensions before the visualization. Remove or explicitly date stale prose such as `Delivery has not started`; generated current state supersedes historical execution assertions without rewriting the historical checkpoint.
|
|
|
|
Visual QA is a governance check, not cosmetic polish:
|
|
|
|
- initial fit must show every node fully;
|
|
- all state values must be legible without mandatory first-use panning/zooming;
|
|
- graph and table values must match;
|
|
- no clipping or overflow;
|
|
- preserve square styling (`border-radius: 0`).
|
|
|
|
A wide left-to-right dependency chain can force unreadable 25% zoom. Prefer a top-to-bottom governed sequence when it keeps the complete graph visible at a readable scale. Put fit options in tested adapter output rather than an untested component literal.
|
|
|
|
## Cross-surface reconciliation
|
|
|
|
A Roadmap fix is incomplete until every sibling surface that repeats or interprets the same state has been checked. Sweep canonical Task evidence, required-child relations, Roadmap graph/table, Kanban Board and Focus prose, Architecture handoff pages, Delivery and release-readiness pages, and their prose-contract tests. Generated current-state components do not neutralize contradictory static prose below them.
|
|
|
|
Preserve immutable admission and approval events as explicitly dated historical snapshots. Add verifier-derived unified delivery beside them rather than rewriting their original conditions. When Releases establishes that an exact source revision was deployed, update mutable evidence summaries with the exact source, GitOps revision, and durable Releases evidence; move governed items only when the transition and roll-up rules are satisfied.
|
|
|
|
When YAML evidence prose contains `#`, do not use an unquoted plain scalar: `Application PR #5 ...` parses as only `Application PR`. Use a folded or quoted scalar and add a loader test against the parsed value so the decisive revision/message markers cannot be silently discarded.
|
|
|
|
## RED-GREEN regressions
|
|
|
|
Add tests before adapter or reconciliation changes:
|
|
|
|
- verified implementation decisions publish true; a hash/evidence mutation publishes false;
|
|
- an active Task derives Feature, Epic, and linked Idea `IN_DELIVERY`;
|
|
- backlog-only required children derive `IN_BACKLOG` unless the product item has exact `IN_DESIGN` evidence;
|
|
- all required children `TO_BE_RELEASED`/`DONE` derive `TO_BE_RELEASED` when at least one remains `TO_BE_RELEASED`;
|
|
- all required children `DONE` derive `DONE`;
|
|
- cancelled children fail aggregation until an explicit Scope decision updates the required set;
|
|
- raw/unverified status does not render;
|
|
- graph nodes, semantic rows, Board, and Focus agree;
|
|
- Roadmap fit/layout configuration prevents initial clipping;
|
|
- real production pipeline probe: `loadDatabase -> validateDatabase -> publicDatabase -> Roadmap/Board adapter` prints the exact state tuple for every rendered Epic/Feature.
|
|
|
|
Run full validators, TypeScript, strict build, browser QA, independent fail-closed review, exact-head CI, merge, and integrated-head CI before calling the correction published.
|