[proposal][tree] Define a hierarchical Tree family for files, plans, sessions, and subagents

Parent: #513
Related: #377, M-COLLECTION-0001, Focus Roving contracts/modules, #388 relationship/anatomy findings, and #521 for later windowing

Goal

Define a portable Tree semantic family for hierarchical navigation and inspection surfaces used by file explorers, plan/todo hierarchies, nested sessions, artifacts, and Agent/subagent activity.

The first slice must be an independently testable cross-host information path. It must not be a visually indented flat list, a File System API, an Agent graph runtime, or a Tree bundled with data loading and virtualization.

This Issue is Agent-ready for the hierarchy, anatomy, focus, selection, and accessibility packet. Reduce the slice from evidence where needed; only materially different viable product directions left after that work become one unresolved-product-direction.

Candidate first-slice scope

A single-root, explicitly authored hierarchy with:

• stable unique item values/keys;
• branch versus leaf facts;
• controlled or uncontrolled expanded-set ownership;
• one current/focusable item;
• single selection only if selection is admitted as a distinct, fully specified state owner;
• dynamic insertion/removal/reorder;
• keyboard navigation over the visible flattened order;
• no lazy loading, drag-and-drop, checkboxes, multi-selection, editing, windowing, or file operations in the first slice.

Reduce the slice further if expansion, focus, and selection cannot be evidenced safely together.

Candidate anatomy

The decision packet must choose a topology that can enforce per-item relationships, for example:

Tree.Root
└─ Tree.Item (repeatable, nested)
   ├─ Tree.ItemTrigger / Row
   └─ optional Tree.Group
      └─ Tree.Item...

A single root-scoped family with domain-wide cardinality is not sufficient if it cannot prove one row/group relationship per repeatable item. Reuse the repository-specific lesson from #388 instead of copying another family-specific ID helper.

Proposed ownership

Tree Root may own

• the logical hierarchy provider;
• expanded item set and controlled/uncontrolled request semantics;
• visible flattened order derived from hierarchy + expansion;
• current/focus navigation state if admitted through existing Focus Roving integration;
• optional single-selection set only through a distinct explicit contract;
• keyboard policy for visible tree navigation;
• typeahead only if separately evidenced and bounded;
• neutral a11y tree semantics and hierarchical facts.

Tree Item may own

• stable item identity within the Tree;
• parent/level/position/set-size facts;
• branch/leaf, expanded, disabled, current/focused, and selected derived facts as authorized;
• explicit activation/expand/collapse requests;
• relationship to its authored child group.

Collection / Focus / A11y retain

• ordered item snapshots and dynamic structure: Collection;
• physical focus sessions and visible focus: Focus;
• host accessibility projection and stable relationship identity: A11y;
• Tree must integrate with, not fork, these domains.

App Maker retains

• file/plan/session/Agent data and loading;
• domain icons, labels, metadata, counts, statuses, and actions;
• file opening, session switching, plan edits, Agent navigation;
• whether children exist but are not yet loaded;
• persistence of expanded/selected state if desired.

Keyboard decision packet

At minimum decide and test:

• Arrow Up/Down over visible order;
• Arrow Right on closed branch / open branch;
• Arrow Left on open branch / child item;
• Home/End;
• Enter/Space activation versus expansion;
• disabled item traversal;
• focus/current behavior when an ancestor collapses;
• item removal/reorder while focused;
• RTL/writing-mode interpretation if portable direction mapping is claimed;
• optional typeahead as included or explicitly deferred.

State-transition packet

• unique/non-empty item value rules;
• duplicate and missing parent diagnostics;
• unknown values in controlled expanded/selected sets;
• structure changes do not emit user-request events;
• controlled request rejection;
• mode/prop changes;
• collapse containing the focused/current item;
• item removal and replacement;
• detach/rematerialize and relationship identity;
• disposal and stale callbacks.

Accessibility packet

• neutral role/state/action model and Web tree/treeitem/group projection where appropriate;
• level, position-in-set, set-size, expanded, selected/current, and disabled facts;
• stable generated host identity for item/group relationships without public DOM IDs;
• behavior when a group is not materialized;
• accessible naming remains authored/App-owned;
• screen-reader and keyboard evidence;
• non-Web hosts are not required to reproduce DOM structure.

Harness proof

After the bounded direction is resolved, prove the first slice in at least two App-owned domains:

1. a static file/artifact hierarchy;
2. a plan or Agent/subagent hierarchy.

Both must use the same Tree semantics while labels, icons, statuses, and activation callbacks remain application-owned.

Evidence plan

• fake structural host: dynamic hierarchy, expansion, current/focus, selection if admitted, duplicates, removal, cleanup;
• WC/React/Vue real authored hierarchy;
• full keyboard journey and focus restoration;
• screen-reader/ARIA inspection on Web;
• narrow layout, zoom/reflow, high contrast;
• repeated mount/detach/rematerialize/dispose;
• no third-party Tree/headless collection implementation.

Acceptance criteria

• First-slice feature set is bounded and explicit.
• Per-item anatomy and stable relationship identity are proven, not inferred from global cardinality.
• Hierarchy, Collection, Focus Roving, selection, A11y, and App Maker ownership are separated.
• Controlled/uncontrolled expansion and complete keyboard/state transition tables are approved.
• Accessibility facts and Web/non-Web projection boundaries are approved.
• Dynamic structure and lifecycle cleanup evidence is red-first.
• #521 integration is deferred or explicitly bounded; Tree does not silently become a virtualizer.
• The packet exposes one accepted dependency-ordered slice; prerequisite and Base work then advance automatically.

Non-goals

• File-system access or file operations.
• Agent execution graph ownership.
• Lazy/asynchronous child loading in the first slice.
• Multi-selection, checkbox Tree, drag-and-drop, inline rename, context menu, or keyboard reordering.
• Windowing/virtualization; tracked in #521.
• Breadcrumb, Sidebar, or Navigation Menu replacement.
• A design-language-specific indentation hack presented as semantics.

Agent-forward execution

Current decision: none for the currently eligible bounded transition.

This bounded work is open for Agent execution. Agents may continue through research or proposal work, implementation of any direction fixed by applicable authority, validation, review response, and the next eligible dependency under current-user or active standing authorization. Routine claiming, implementation details, CI repair, review, ready-for-review, and merge mechanics are not attended decisions.

Pause only for:

1. unresolved-product-direction: applicable authority and evidence leave materially different semantic, ownership, public-guarantee, lifecycle, or compatibility choices open.
2. privileged-or-irreversible-operation: publication or release, access, secrets, rulesets, security disclosure, a provenance exception, or another action that cannot be safely bounded and recovered.

For every pull-request transition, bind collection, review, and integration to the live exact head. Require trusted repository CI and DCO status plus independent source/provenance review; an independent reviewer who is not the PR author or any commit contributor; no active, non-dismissed CHANGES_REQUESTED anywhere in the cumulative review history; and every applicable review thread resolved. A draft pull request may be reviewed and remediated but must not be merged. Respect live permission and repository rules, use an atomic lease or idempotency key and durable receipt, reconcile an unknown outcome once before any retry, and never force/admin-bypass or blindly retry.

Start with parent #513 and the referenced Collection, Focus Roving, A11y, #388, and #521 materials; no implementation file or test path is named. First bound and approve one dependency-ordered Tree slice, then prove it with the fake structural host and WC/React/Vue authored hierarchies. Done means ownership, anatomy, keyboard/state transitions, accessibility boundaries, dynamic/lifecycle cleanup, and deferred windowing are evidenced without taking over app data.