corp-v1-channel-scope/references/roadmap-multidimensional-state.md

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.