Issue hierarchy: support grandchildren (parent of parent)

[berenddeboer]

Summary

Extend Supported Issue Hierarchy beyond a single parent level so an Issue may be both a child of a Parent Issue and a parent of its own children (grandchildren / “parent of parent”). Today the harness treats a hierarchy with a grandchild as unsupported in its entirety.

Why v1 stopped at one level

CONTEXT defines Supported Issue Hierarchy as a root with optional direct children only; a hierarchy containing a grandchild is unsupported. Child Issues are defined as having no children of their own.

The deliberate v1 limit was not primarily “Forge cannot express this” (GitHub sub-issues can nest). It was product/UI: we did not have a clear visual design for multi-level hierarchy in the harness (lanes, Issue lists, Parent Issue actions, depth cues) and chose not to ship deeper structure until that was solvable.

Concrete friction: epic + mid-level spec + leaf tickets (e.g. readiness epic → model-selection parent → leaf tickets) forces a flat two-parent setup (two top-level parents, each with only leaves) so the harness can enroll work, instead of a single nested tree operators already use on GitHub.

Current behaviour (domain)

Term	Today
Parent Issue	Root with ≥1 direct children; not itself a Work Item
Child Issue	Direct child; no children of its own
Leaf Issue	No children (Standalone or Child); only leaves are Work Item units
Grandchild / nested parent	Hierarchy unsupported in its entirety

Related: Implement All with Auto-merge is Parent-scoped over direct open children only (ADR 0040). Only Leaf Issues are work units (ADR 0006).

Problem for operators

• Real plans often need spec → tickets under an epic (parent of parent).
• Workarounds: keep mid-level issues as standalone parents (lose single epic tree in the harness), or flatten everything under one parent (lose mid-level grouping).
• GitHub UI already shows nested sub-issues; the harness rejects or ignores depth beyond one.

Goals (investigation)

1. Visual design first — how multi-level hierarchy appears in Issue store / Parent views / Implement All (indent, collapse, badges, max depth). This is the open question that blocked v1.
2. Domain model — redefine Supported Issue Hierarchy (max depth? arbitrary GitHub depth capped?). Update CONTEXT glossary (Parent / Child / Leaf; remove or revise “Child has no children”).
3. Work units — keep “only leaves get Work Items” unless product deliberately changes ADR 0006.
4. Implement All with Auto-merge — enroll only leaves under a selected ancestor, or only direct children, or recursive open leaves? Atomic enrollment rules.
5. Reconciliation — store parent pointers for intermediate nodes; unsupported-depth handling during transition.
6. GitLab — still no hierarchy today; confirm multi-level remains GitHub-only unless GitLab gains equivalent structure.

Non-goals (unless decided otherwise)

• Cross-Repository hierarchy (already unsupported).
• Treating Parent Issues as Work Items.
• Unlimited depth without a UX cap if display requires one.

Acceptance (draft)

• Agreed visual treatment for at least depth-2 (root → mid → leaf) in the operator UI.
• CONTEXT + ADRs updated for Supported Issue Hierarchy and leaf enrollment.
• Issue store / reconciliation accept and display depth-2 (or agreed max) without marking the whole hierarchy unsupported.
• Implement All (or successor) has explicit, documented behaviour for multi-level parents.
• Leaf Work Item lifecycle unchanged for true leaves.

Related

• CONTEXT: Supported Issue Hierarchy, Parent Issue, Child Issue, Leaf Issue, Implement All with Auto-merge.
• ADR 0006 (only leaves are work units), ADR 0040 (atomic parent implement).
• Practical example: Bedrock readiness epic vs model-selection parent tickets (Claude Code: Amazon Bedrock readiness (MVP) #799 / Claude Code: Bedrock model selection in Settings #800 hierarchy discussion).

Notes

Captured after operators needed nested GitHub sub-issues for specs-and-tickets under an epic and the harness could only attach a single parent level.