Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

fix: correct stale doc comments in layout priority system (#1092)

Maximilian Roos87c671e22b43
diff --git a/src/commands/list/layout.rs b/src/commands/list/layout.rs
index 3a88ddaa7..59050f317 100644
--- a/src/commands/list/layout.rs
+++ b/src/commands/list/layout.rs
@@ -54,22 +54,22 @@
//! final_priority = base_priority + empty_penalty
//! ```
//!
-//! **Base priorities** (1-11) are determined by **user need hierarchy** - what questions users need
+//! **Base priorities** (0-12) are determined by **user need hierarchy** - what questions users need
//! answered when scanning worktrees:
+//! - 0: Gutter (always present)
//! - 1: Branch (identity - "what is this?")
-//! - 2: Working diff (critical - "do I need to commit?")
-//! - 3: Ahead/behind (critical - "am I out of sync?")
-//! - 4-10: Context (work volume, states, path, time, CI, etc.)
-//! - 11: Message (nice-to-have, space-hungry)
+//! - 2-4: Critical (status, working diff, ahead/behind)
+//! - 5-11: Context (CI, branch diff, path, upstream, URL, commit, time)
+//! - 12: Message (nice-to-have, space-hungry)
//!
//! **Empty penalty**: +10 if column has no data (only header)
-//! - Empty working_diff: 2 + 10 = priority 12
-//! - Empty ahead/behind: 3 + 10 = priority 13
+//! - Empty working_diff: 3 + 10 = priority 13
+//! - Empty ahead/behind: 4 + 10 = priority 14
//! - etc.
//!
//! This creates two effective priority tiers:
-//! - **Tier 1 (priorities 1-11)**: Columns with actual data
-//! - **Tier 2 (priorities 12-21)**: Empty columns (visual consistency)
+//! - **Tier 1 (priorities 0-12)**: Columns with actual data
+//! - **Tier 2 (priorities 12-22)**: Empty columns (visual consistency)
//!
//! The empty penalty is large (+10) but not infinite, so empty columns maintain their relative
//! ordering (empty working_diff still ranks higher than empty ci_status) for visual consistency.
@@ -83,7 +83,7 @@
//! 2. Show nice-to-have data (message, commit hash) when space allows
//! 3. Maintain visual consistency - empty columns in predictable positions at wide widths
//!
-//! **Key decision**: Message sits at the boundary (priority 11). Empty columns (priority 12+)
+//! **Key decision**: Message sits at the boundary (priority 12). Empty columns (priority 12+)
//! rank below message, so:
//! - Narrow terminals: Data columns + message (hide empty columns)
//! - Wide terminals: Data columns + message + empty columns (visual consistency)
@@ -103,19 +103,17 @@
//!
//! ## Special Cases
//!
-//! Three columns have non-standard behavior that extends beyond the basic two-tier model:
+//! Some columns have non-standard behavior that extends beyond the basic two-tier model:
//!
-//! 1. **BranchDiff** - Visibility gate (`show_full` flag)
-//! - Hidden by default as too noisy for typical usage
-//! - Only allocated when `show_full=true` (match guard skips if false)
+//! 1. **BranchDiff** and **CiStatus** - Visibility gate (`show_full` flag)
+//! - Both require `show_full=true` (hidden by default as too noisy for typical usage)
+//! - Gated via `skip_tasks`: when `show_full=false`, their `TaskKind` is in `skip_tasks`
+//! and the column is filtered out entirely (bypasses the tier system)
+//! - Within the visibility gate, follows normal two-tier priority
+//! (BranchDiff: 6/16, CiStatus: 5/15)
//!
-//! 2. **CiStatus** - Visibility gate (`fetch_ci` flag)
-//! - Only shown when `fetch_ci=true` (when CI data was requested)
-//! - Bypasses the tier system entirely when `fetch_ci=false`
-//! - Within the visibility gate, follows normal two-tier priority (priority 9 with data, 19 when empty)
-//!
-//! 3. **Message** - Flexible sizing with post-allocation expansion
-//! - Allocated at priority 11 with flexible width (min 20, preferred 50)
+//! 2. **Message** - Flexible sizing with post-allocation expansion
+//! - Allocated at priority 12 with flexible width (min 20, preferred 50)
//! - After all columns allocated (including empty ones), expands up to max 100 using leftover space
//! - Two-step process ensures critical columns get space before message grows
//!
@@ -127,7 +125,7 @@
//! // Build candidates from centralized COLUMN_SPECS registry
//! let mut candidates: Vec<ColumnCandidate> = COLUMN_SPECS
//! .iter()
-//! .filter(|spec| /* visibility gates: show_full, fetch_ci */)
+//! .filter(|spec| /* visibility gate: skip_tasks */)
//! .map(|spec| ColumnCandidate {
//! spec,
//! priority: if spec.kind.has_data(&data_flags) {