EPIC: Hierarchical team-prefix grouping (multi-level headings)

[vibou]

Context

The original request in this issue proposes organizing --group-by-team-prefix results with a hierarchy logic instead of the current flat, single-level grouping:

1. Hierarchical prefixes: a prefix chain like gamme-/squad- should produce nested headings (## gamme-client / ### squad-dashboard).
2. Grouping overlapping levels: when team names themselves overlap (e.g. gamme-lead-client and gamme-lead-client-p1), nest them automatically instead of listing them as unrelated siblings.
3. Advanced/consolidated rendering: collapse deep single-branch chains into one heading with a summary suffix (e.g. gamme-lead-client (including p1, unset, etc.)).

This is a substantial change touching the grouping algorithm, both output formats (markdown/JSON), the interactive TUI, and the --pick-team feature. It is tracked as an EPIC and split into the 7 sub-issues below.

Solution

Implement all 3 mechanisms as a coherent hierarchical model:

• A tree-shaped grouping result (replacing the current flat TeamSection[]) built from a CLI-declared prefix chain (/ for depth, , for independent sibling hierarchies) plus automatic nesting of overlapping team names.
• Depth-aware rendering in both markdown (##/###/####) and JSON output.
• Depth-aware TUI rendering and navigation.
• --pick-team extended to resolve a section at any depth, not just the leaf level.

This is a breaking change to the --group-by-team-prefix / --pick-team CLI surface and to the JSON output shape, and will ship as a major release per AGENTS.md.

Implementation overview

flowchart TD
    CLI["github-code-search.ts<br/>--group-by-team-prefix chain grammar"] --> Parse["Parse chains #6<br/>e.g. gamme-/squad-,chapter-"]
    Parse --> Fetch["fetchRepoTeams (api.ts)<br/>flattened prefix list, unchanged"]
    Fetch --> Algo["groupByTeamHierarchy #1<br/>src/group.ts"]
    Algo --> Tree["TeamSection tree<br/>{label, groups, level, children}"]
    Tree --> Consolidate["Consolidation #2<br/>collapse single-branch chains"]
    Consolidate --> Flatten["flatten/rebuild helpers<br/>RepoGroup.sectionLabel + level"]
    Flatten --> MD["buildMarkdownOutput #3<br/>##/###/#### headings"]
    Flatten --> JSON["buildJsonOutput #3<br/>nested sections"]
    Flatten --> TUI["buildRows / render.ts #4<br/>nested header rows"]
    Tree --> Pick["--pick-team path addressing #5<br/>applyTeamPick / moveRepoToSection"]
    Pick --> Flatten
    MD --> Docs["docs/usage/team-grouping.md #7"]
    JSON --> Docs
    TUI --> Docs

Loading

Sub-issues (in dependency order):

• [1/7] Data model & core hierarchical grouping algorithm #177 - [1/7] Data model & core hierarchical grouping algorithm
• [2/7] Advanced consolidated rendering #178 - [2/7] Advanced consolidated rendering
• [3/7] Markdown & JSON output for N-level headings #179 - [3/7] Markdown & JSON output for N-level headings
• [4/7] TUI rendering & navigation for N-level headers #180 - [4/7] TUI rendering & navigation for N-level headers
• [5/7] --pick-team / re-pick across all hierarchy levels #181 - [5/7] --pick-team / re-pick across all hierarchy levels
• [6/7] CLI wiring end-to-end #182 - [6/7] CLI wiring end-to-end
• [7/7] Documentation & changelog #183 - [7/7] Documentation & changelog

Acceptance Criteria

• All 7 sub-issues above are closed and linked as native GitHub sub-issues of this EPIC.
• --group-by-team-prefix "gamme-/squad-" produces nested ##/### markdown headings and a matching nested JSON structure.
• Team names that overlap within one level (e.g. gamme-lead-client, gamme-lead-client-p1) are automatically nested rather than shown as unrelated siblings.
• Consolidated rendering mode collapses single-branch chains into one heading with an "(including ...)" summary.
• --pick-team (CLI and interactive p/t) resolves and reassigns sections at any hierarchy depth.
• docs/usage/team-grouping.md and docs/reference/cli-options.md reflect the new syntax end to end.

Definition of Done

• All sub-issue PRs merged into a shared long-lived feature branch feat/hierarchical-team-grouping, then merged into main.
• Full validation suite green on main: bun test, bun run lint, bun run format:check, bun run knip, bun run build.ts.
• Major release cut per AGENTS.md release process, including the required blog post (highlights gathered interactively from the user before writing).
• CHANGELOG.md updated, no _pending_ rows left.