Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
docs(list): drop the stale-branch and dirty-tree skips from JSON help (#4359)
Worktrunk Bot64ead5388aee
diff --git a/docs/public/schema/list-v2.json b/docs/public/schema/list-v2.jsonindex 3f338febb..e0eb31444 100644--- a/docs/public/schema/list-v2.json+++ b/docs/public/schema/list-v2.json@@ -217,7 +217,7 @@},"integration": {"$ref": "#/$defs/Nullable_JsonIntegration",- "description": "How committed content is integrated; absent when determined\nnot-integrated, null when undetermined (dirty trees skip the\nexpensive checks)."+ "description": "How committed content is integrated; absent when determined\nnot-integrated, null when undetermined (a probe timed out or was\nskipped)."},"merge_conflicts": {"description": "A merge into the default branch would conflict based on committed\ncontent and tracked worktree changes (local `merge-tree` simulation);\nnull while unresolved.",diff --git a/docs/src/content/docs/list.md b/docs/src/content/docs/list.mdindex bf0fb9b35..7d3d2ed09 100644--- a/docs/src/content/docs/list.md+++ b/docs/src/content/docs/list.md@@ -221,7 +221,7 @@ These appear across all columns while the table is loading:| Symbol | Meaning ||--------|---------|-| `·` | Data is loading, or collection timed out / branch too stale |+| `·` | Data is loading, or collection timed out |---@@ -269,9 +269,9 @@ How "no value" reads:- **Absent** — nothing to report: not applicable (`worktree` on a branch-onlyrow), not requested this run (the envelope's `collected` records what was),or determined-empty (no PR, no lock, not integrated).-- **`null`** — requested but not determined: a task timed out, the branch was- too stale for the expensive checks, or a forge fetch failed. This is the- JSON form of the table's `·` placeholder.+- **`null`** — requested but not determined: a task timed out, a check was+ skipped, or a forge fetch failed. This is the JSON form of the table's `·`+ placeholder.jq treats absent and `null` identically in path expressions, so filters needno null checks; `has()` distinguishes the two when it matters.@@ -354,7 +354,7 @@ Independent facts; the table's priority-collapsed symbol is `display.state`.| `behind` | number/null | Commits behind the default branch (null for orphans) || `diff` | object/null | Lines changed vs the default branch: `{added, deleted}` || `orphan` | boolean/null | No common ancestor with the default branch |-| `integration` | object/null | `{reason}` — which check found the content [integrated](/remove/#branch-cleanup) (see [integration reasons](#integration-reasons)); absent when determined not-integrated, null when a dirty tree skipped the checks |+| `integration` | object/null | `{reason}` — which check found the content [integrated](/remove/#branch-cleanup) (see [integration reasons](#integration-reasons)); absent when determined not-integrated, null when undetermined (a check timed out or was skipped) || `merge_conflicts` | boolean/null | Merging into the default branch would conflict, simulated locally with `git merge-tree` |### upstream object@@ -426,7 +426,7 @@ The single highest-priority state describing the branch's relation to the defaul### integration reasons-`default_branch.integration.reason` records which check matched. Checks run cheapest-first and the first match wins. JSON-only — every reason renders as the same `⊂`:+`default_branch.integration.reason` records which check matched. Checks run cheapest-first and the first match wins. The reason itself is JSON-only: the table shows `"same_commit"` as `_` (or `–` with uncommitted changes) and every other reason as `⊂` when the working tree is clean:| Value | Meaning ||-------|---------|diff --git a/plugins/worktrunk/skills/worktrunk/reference/list.md b/plugins/worktrunk/skills/worktrunk/reference/list.mdindex 3f2e56acc..93457d45a 100644--- a/plugins/worktrunk/skills/worktrunk/reference/list.md+++ b/plugins/worktrunk/skills/worktrunk/reference/list.md@@ -205,7 +205,7 @@ These appear across all columns while the table is loading:| Symbol | Meaning ||--------|---------|-| `·` | Data is loading, or collection timed out / branch too stale |+| `·` | Data is loading, or collection timed out |---@@ -253,9 +253,9 @@ How "no value" reads:- **Absent** — nothing to report: not applicable (`worktree` on a branch-onlyrow), not requested this run (the envelope's `collected` records what was),or determined-empty (no PR, no lock, not integrated).-- **`null`** — requested but not determined: a task timed out, the branch was- too stale for the expensive checks, or a forge fetch failed. This is the- JSON form of the table's `·` placeholder.+- **`null`** — requested but not determined: a task timed out, a check was+ skipped, or a forge fetch failed. This is the JSON form of the table's `·`+ placeholder.jq treats absent and `null` identically in path expressions, so filters needno null checks; `has()` distinguishes the two when it matters.@@ -338,7 +338,7 @@ Independent facts; the table's priority-collapsed symbol is `display.state`.| `behind` | number/null | Commits behind the default branch (null for orphans) || `diff` | object/null | Lines changed vs the default branch: `{added, deleted}` || `orphan` | boolean/null | No common ancestor with the default branch |-| `integration` | object/null | `{reason}` — which check found the content [integrated](https://worktrunk.dev/remove/#branch-cleanup) (see [integration reasons](#integration-reasons)); absent when determined not-integrated, null when a dirty tree skipped the checks |+| `integration` | object/null | `{reason}` — which check found the content [integrated](https://worktrunk.dev/remove/#branch-cleanup) (see [integration reasons](#integration-reasons)); absent when determined not-integrated, null when undetermined (a check timed out or was skipped) || `merge_conflicts` | boolean/null | Merging into the default branch would conflict, simulated locally with `git merge-tree` |### upstream object@@ -410,7 +410,7 @@ The single highest-priority state describing the branch's relation to the defaul### integration reasons-`default_branch.integration.reason` records which check matched. Checks run cheapest-first and the first match wins. JSON-only — every reason renders as the same `⊂`:+`default_branch.integration.reason` records which check matched. Checks run cheapest-first and the first match wins. The reason itself is JSON-only: the table shows `"same_commit"` as `_` (or `–` with uncommitted changes) and every other reason as `⊂` when the working tree is clean:| Value | Meaning ||-------|---------|diff --git a/skills/worktrunk/reference/list.md b/skills/worktrunk/reference/list.mdindex 3f2e56acc..93457d45a 100644--- a/skills/worktrunk/reference/list.md+++ b/skills/worktrunk/reference/list.md@@ -205,7 +205,7 @@ These appear across all columns while the table is loading:| Symbol | Meaning ||--------|---------|-| `·` | Data is loading, or collection timed out / branch too stale |+| `·` | Data is loading, or collection timed out |---@@ -253,9 +253,9 @@ How "no value" reads:- **Absent** — nothing to report: not applicable (`worktree` on a branch-onlyrow), not requested this run (the envelope's `collected` records what was),or determined-empty (no PR, no lock, not integrated).-- **`null`** — requested but not determined: a task timed out, the branch was- too stale for the expensive checks, or a forge fetch failed. This is the- JSON form of the table's `·` placeholder.+- **`null`** — requested but not determined: a task timed out, a check was+ skipped, or a forge fetch failed. This is the JSON form of the table's `·`+ placeholder.jq treats absent and `null` identically in path expressions, so filters needno null checks; `has()` distinguishes the two when it matters.@@ -338,7 +338,7 @@ Independent facts; the table's priority-collapsed symbol is `display.state`.| `behind` | number/null | Commits behind the default branch (null for orphans) || `diff` | object/null | Lines changed vs the default branch: `{added, deleted}` || `orphan` | boolean/null | No common ancestor with the default branch |-| `integration` | object/null | `{reason}` — which check found the content [integrated](https://worktrunk.dev/remove/#branch-cleanup) (see [integration reasons](#integration-reasons)); absent when determined not-integrated, null when a dirty tree skipped the checks |+| `integration` | object/null | `{reason}` — which check found the content [integrated](https://worktrunk.dev/remove/#branch-cleanup) (see [integration reasons](#integration-reasons)); absent when determined not-integrated, null when undetermined (a check timed out or was skipped) || `merge_conflicts` | boolean/null | Merging into the default branch would conflict, simulated locally with `git merge-tree` |### upstream object@@ -410,7 +410,7 @@ The single highest-priority state describing the branch's relation to the defaul### integration reasons-`default_branch.integration.reason` records which check matched. Checks run cheapest-first and the first match wins. JSON-only — every reason renders as the same `⊂`:+`default_branch.integration.reason` records which check matched. Checks run cheapest-first and the first match wins. The reason itself is JSON-only: the table shows `"same_commit"` as `_` (or `–` with uncommitted changes) and every other reason as `⊂` when the working tree is clean:| Value | Meaning ||-------|---------|diff --git a/src/cli/mod.rs b/src/cli/mod.rsindex 3f90a9358..ed3db5389 100644--- a/src/cli/mod.rs+++ b/src/cli/mod.rs@@ -1005,7 +1005,7 @@ These appear across all columns while the table is loading:| Symbol | Meaning ||--------|---------|-| `·` | Data is loading, or collection timed out / branch too stale |+| `·` | Data is loading, or collection timed out |---@@ -1053,9 +1053,9 @@ How "no value" reads:- **Absent** — nothing to report: not applicable (`worktree` on a branch-onlyrow), not requested this run (the envelope's `collected` records what was),or determined-empty (no PR, no lock, not integrated).-- **`null`** — requested but not determined: a task timed out, the branch was- too stale for the expensive checks, or a forge fetch failed. This is the- JSON form of the table's `·` placeholder.+- **`null`** — requested but not determined: a task timed out, a check was+ skipped, or a forge fetch failed. This is the JSON form of the table's `·`+ placeholder.jq treats absent and `null` identically in path expressions, so filters needno null checks; `has()` distinguishes the two when it matters.@@ -1138,7 +1138,7 @@ Independent facts; the table's priority-collapsed symbol is `display.state`.| `behind` | number/null | Commits behind the default branch (null for orphans) || `diff` | object/null | Lines changed vs the default branch: `{added, deleted}` || `orphan` | boolean/null | No common ancestor with the default branch |-| `integration` | object/null | `{reason}` — which check found the content [integrated](/remove/#branch-cleanup) (see [integration reasons](#integration-reasons)); absent when determined not-integrated, null when a dirty tree skipped the checks |+| `integration` | object/null | `{reason}` — which check found the content [integrated](/remove/#branch-cleanup) (see [integration reasons](#integration-reasons)); absent when determined not-integrated, null when undetermined (a check timed out or was skipped) || `merge_conflicts` | boolean/null | Merging into the default branch would conflict, simulated locally with `git merge-tree` |### upstream object@@ -1210,7 +1210,7 @@ The single highest-priority state describing the branch's relation to the defaul### integration reasons-`default_branch.integration.reason` records which check matched. Checks run cheapest-first and the first match wins. JSON-only — every reason renders as the same `⊂`:+`default_branch.integration.reason` records which check matched. Checks run cheapest-first and the first match wins. The reason itself is JSON-only: the table shows `"same_commit"` as `_` (or `–` with uncommitted changes) and every other reason as `⊂` when the working tree is clean:| Value | Meaning ||-------|---------|diff --git a/src/commands/list/collect/execution.rs b/src/commands/list/collect/execution.rsindex 91be25906..6b9ff95cf 100644--- a/src/commands/list/collect/execution.rs+++ b/src/commands/list/collect/execution.rs@@ -12,9 +12,9 @@//! `refresh_status_symbols` resolves each gate independently, reading that//! gate's required fields on `ListItem` / `WorktreeData` as they become//! `Some`. Tasks that *will* run are written by the drain as their results-//! arrive. Tasks that will *not* run (stale branches skip expensive tasks,-//! unborn branches skip commit-dependent tasks, the column plan excludes them,-//! branches with no worktree have no worktree-only tasks) have their fields+//! arrive. Tasks that will *not* run (unborn branches skip commit-dependent+//! tasks, the column plan excludes them, branches with no worktree have no+//! worktree-only tasks) have their fields//! seeded here via [`seed_skipped_task_defaults`] with conservative defaults//! — otherwise the fields would stay `None` forever and their gate would//! never resolve.@@ -126,7 +126,7 @@ impl ExpectedResults {////// `refresh_status_symbols` keeps gates at `None` while their inputs are/// unloaded, which renders as the `·` placeholder. For tasks that will-/// *never* run (stale branch, a task no rendered column needs, unborn item missing+/// *never* run (a task no rendered column needs, unborn item missing/// commit-dependent tasks, prunable worktree), seeding a conservative/// default up front lets the gate resolve normally instead of showing `·`/// forever.@@ -276,7 +276,7 @@ pub(super) fn seed_prunable_item(item: &mut ListItem) {////// **Side effects on `item`:**/// - Seeds conservative sentinels on fields corresponding to tasks that will-/// *not* run (stale/unborn/skipped). See module docstring.+/// *not* run (unborn/skipped). See module docstring.////// **Side effects on `tx`:**/// - Sends an immediate `TaskResult::UrlStatus { url: Some, active: None }`@@ -287,7 +287,7 @@ pub(super) fn seed_prunable_item(item: &mut ListItem) {/// directly here would leave it stuck behind whatever task happens to/// complete first.///-/// Task preconditions (stale branch, unborn branch, missing llm_command) are+/// Task preconditions (unborn branch, missing llm_command) are/// enforced here — not in callers. This function is called from both/// `collect()` and `populate_item()`, so guards must live here to cover all/// entry points.diff --git a/src/commands/list/json_v2.rs b/src/commands/list/json_v2.rsindex 4a4c26591..02a37a82c 100644--- a/src/commands/list/json_v2.rs+++ b/src/commands/list/json_v2.rs@@ -333,8 +333,8 @@ pub struct JsonDefaultBranch {pub orphan: Option<bool>,/// How committed content is integrated; absent when determined- /// not-integrated, null when undetermined (dirty trees skip the- /// expensive checks).+ /// not-integrated, null when undetermined (a probe timed out or was+ /// skipped).#[serde(skip_serializing_if = "Tri::is_absent")]pub integration: Tri<JsonIntegration>,diff --git a/src/commands/list/model/status_symbols.rs b/src/commands/list/model/status_symbols.rsindex 49f22b47b..a416b1c27 100644--- a/src/commands/list/model/status_symbols.rs+++ b/src/commands/list/model/status_symbols.rs@@ -130,10 +130,10 @@//! seeded, gate 3 resolves to `None` for unborn non-main items and the row//! still renders.//!-//! **Exception — stale branches and `--skip-tasks`:** fields for+//! **Exception — tasks the column plan skips:** fields for//! deliberately-skipped tasks are seeded at spawn time with conservative-//! defaults. Stale branches can render a less-specific main-state symbol-//! than fresh ones (e.g., `↕` instead of `⊂`).+//! defaults. Items with skipped integration tasks can render a less-specific+//! main-state symbol (e.g., `↕` instead of `⊂`).//!//! # Gate 4: Upstream divergence (position 5)//!diff --git a/tests/snapshots/integration__integration_tests__help__help_list_long.snap b/tests/snapshots/integration__integration_tests__help__help_list_long.snapindex 8ab8a2039..c9c1840ec 100644--- a/tests/snapshots/integration__integration_tests__help__help_list_long.snap+++ b/tests/snapshots/integration__integration_tests__help__help_list_long.snap@@ -281,9 +281,9 @@ field.These appear across all columns while the table is loading:- Symbol Meaning- ────── ───────────────────────────────────────────────────────────- [2m·[0m Data is loading, or collection timed out / branch too stale+ Symbol Meaning+ ────── ────────────────────────────────────────+ [2m·[0m Data is loading, or collection timed out[2m────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────[0m@@ -329,9 +329,9 @@ How "no value" reads:- [1mAbsent[0m — nothing to report: not applicable ([2mworktree[0m on a branch-onlyrow), not requested this run (the envelope's [2mcollected[0m records what was),or determined-empty (no PR, no lock, not integrated).-- [1m[2mnull[0m[0m — requested but not determined: a task timed out, the branch was- too stale for the expensive checks, or a forge fetch failed. This is the- JSON form of the table's [2m·[0m placeholder.+- [1m[2mnull[0m[0m — requested but not determined: a task timed out, a check was+ skipped, or a forge fetch failed. This is the JSON form of the table's [2m·[0m+ placeholder.jq treats absent and [2mnull[0m identically in path expressions, so filters needno null checks; [2mhas()[0m distinguishes the two when it matters.@@ -408,14 +408,14 @@ The five change flags map to the Working tree symbols ([2mrenamed[0m and [2mdIndependent facts; the table's priority-collapsed symbol is [2mdisplay.state[0m.- Field Type Description- ─────────────── ──────────── ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────- [2mahead[0m number/null Commits ahead of the default branch (null for orphans)- [2mbehind[0m number/null Commits behind the default branch (null for orphans)- [2mdiff[0m object/null Lines changed vs the default branch: [2m{added, deleted}[0m- [2morphan[0m boolean/null No common ancestor with the default branch- [2mintegration[0m object/null [2m{reason}[0m — which check found the content integrated (see integration reasons); absent when determined not-integrated, null when a dirty tree skipped the checks- [2mmerge_conflicts[0m boolean/null Merging into the default branch would conflict, simulated locally with [2mgit merge-tree[0m+ Field Type Description+ ─────────────── ──────────── ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────+ [2mahead[0m number/null Commits ahead of the default branch (null for orphans)+ [2mbehind[0m number/null Commits behind the default branch (null for orphans)+ [2mdiff[0m object/null Lines changed vs the default branch: [2m{added, deleted}[0m+ [2morphan[0m boolean/null No common ancestor with the default branch+ [2mintegration[0m object/null [2m{reason}[0m — which check found the content integrated (see integration reasons); absent when determined not-integrated, null when undetermined (a check timed out or was skipped)+ [2mmerge_conflicts[0m boolean/null Merging into the default branch would conflict, simulated locally with [2mgit merge-tree[0m[32mupstream object[0m@@ -486,7 +486,7 @@ The single highest-priority state describing the branch's relation to the defaul[32mintegration reasons[0m-[2mdefault_branch.integration.reason[0m records which check matched. Checks run cheapest-first and the first match wins. JSON-only — every reason renders as the same [2m⊂[0m:+[2mdefault_branch.integration.reason[0m records which check matched. Checks run cheapest-first and the first match wins. The reason itself is JSON-only: the table shows [2m"same_commit"[0m as [2m_[0m (or [2m–[0m with uncommitted changes) and every other reason as [2m⊂[0m when the working tree is clean:Value Meaning──────────────────── ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────diff --git a/tests/snapshots/integration__integration_tests__help__help_list_narrow_80.snap b/tests/snapshots/integration__integration_tests__help__help_list_narrow_80.snapindex 9198455e5..db8e55156 100644--- a/tests/snapshots/integration__integration_tests__help__help_list_narrow_80.snap+++ b/tests/snapshots/integration__integration_tests__help__help_list_narrow_80.snap@@ -344,9 +344,9 @@ field.These appear across all columns while the table is loading:- Symbol Meaning- ────── ───────────────────────────────────────────────────────────- [2m·[0m Data is loading, or collection timed out / branch too stale+ Symbol Meaning+ ────── ────────────────────────────────────────+ [2m·[0m Data is loading, or collection timed out[2m────────────────────────────────────────────────────────────────────────────────[0m@@ -396,9 +396,9 @@ How "no value" reads:- [1mAbsent[0m — nothing to report: not applicable ([2mworktree[0m on a branch-onlyrow), not requested this run (the envelope's [2mcollected[0m records what was),or determined-empty (no PR, no lock, not integrated).-- [1m[2mnull[0m[0m — requested but not determined: a task timed out, the branch was- too stale for the expensive checks, or a forge fetch failed. This is the- JSON form of the table's [2m·[0m placeholder.+- [1m[2mnull[0m[0m — requested but not determined: a task timed out, a check was+ skipped, or a forge fetch failed. This is the JSON form of the table's [2m·[0m+ placeholder.jq treats absent and [2mnull[0m identically in path expressions, so filters needno null checks; [2mhas()[0m distinguishes the two when it matters.@@ -505,7 +505,8 @@ Independent facts; the table's priority-collapsed symbol is [2mdisplay.state[0l[2mintegrat[0m object/null [2m{reason}[0m — which check found the content integrated (see[2mion[0m integration reasons); absent when determined- not-integrated, null when a dirty tree skipped the checks+ not-integrated, null when undetermined (a check timed out+ or was skipped)[2mmerge_co[0m boolean/nul Merging into the default branch would conflict, simulated[2mnflicts[0m l locally with [2mgit merge-tree[0m@@ -595,8 +596,9 @@ full meaning of each value ([2m"is_main"[0m, [2m"orphan"[0m, [2m"empty"[0m[32mintegration reasons[0m[2mdefault_branch.integration.reason[0m records which check matched. Checks run-cheapest-first and the first match wins. JSON-only — every reason renders as the- same [2m⊂[0m:+cheapest-first and the first match wins. The reason itself is JSON-only: the+table shows [2m"same_commit"[0m as [2m_[0m (or [2m–[0m with uncommitted changes) and every other+reason as [2m⊂[0m when the working tree is clean:Value Meaning────────────── ───────────────────────────────────────────────────────────────