[patrickleet]

Problem and resulting documentation

The existing guide did not explain how a background consumer can select one worktree set and obtain its repositories without collecting Git state that it immediately observes again. It also did not distinguish all-set listing from current-set behavior.

Document list [NAME], inferred current-set selection and the independent --metadata-only option. The guide now explains list versus detailed status, output fields, failures, and polling expectations.

Before and after usage

Before, a topology-only consumer could request detailed status and discard extra Git facts:

meta git worktree status example --recursive --json

After, select only the required observation detail:

meta git worktree list example --recursive --metadata-only --json

Inside .worktrees/example/ or any descendant, omit the name:

meta git worktree list
meta git worktree list --recursive --metadata-only --json

Plain list retains branch/dirty summaries; metadata-only returns aliases, physical checkout paths and canonical source paths under the existing worktrees envelope. Explicit NAME overrides inference. Outside a worktree, omitted NAME retains all-set listing. status NAME remains the detailed Git-state command.

Contracts clarified

• Metadata-only launches no Git probes but still traverses the filesystem under a finite budget.
• Recursion includes nested realized repositories; metadata-only without recursion retains legacy traversal boundaries.
• Invalid, missing or empty selected sets are errors. Recursive all-set listing reports failed sets as warnings while preserving healthy sets.
• Consumers must check aggregate warnings, retain last-observed data as such, poll sparingly and back off after failures.
• Implicit host scoping obtains metadata paths without per-member branch probes. No kernel-crash-prevention claim is made.

Dependencies and validation

Publish with meta_cli #35 and meta_git_cli #29; ATC #554 consumes the API.

Documentation-only changes; formatting/whitespace checks passed. Examples and response fields were checked against the implementation and installed explicit/inferred commands on the actual 14-repository Harmony worktree. This documents the final list API; the earlier unreleased members command has been removed.

Tracked by [[tasks/harmony-2613]].

Summary by CodeRabbit

• Documentation
  • Documented how to list worktree sets by name, use the enclosing set implicitly, or list all sets outside a worktree.
  • Added guidance on errors for invalid or unavailable sets and on metadata-only output, including nested repository discovery and its limitations.
  • Clarified worktree scoping, plugin list selection, traversal boundaries, and polling.

Review follow-up

The guide now clarifies that membership errors stop CLI dispatch before ordinary configuration fallback and that plugin list selection follows the protocol request directory even when the process starts elsewhere. Companion commits are Meta CLI 9de045f and Meta Git 52e1322; CLI integration/protocol tests and Clippy passed.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Source mode: Auto
• Repository: Unavailable
• Branch: Unavailable
• File: No configuration file from this repository applied
• Commit: Unavailable
• Layers: Organization UI
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: 58b27a28-de3e-43cb-b5f1-bd9f665a7d28

📥 Commits

Reviewing files that changed from the base of the PR and between e899d90 and 9ecf934.

📒 Files selected for processing: 1

• docs/advanced_usage.md

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

Walkthrough

The advanced usage guide now documents worktree set selection, metadata-only output, recursive metadata discovery, error and warning behavior, implicit worktree scoping, plugin list selection, bounded traversal, and polling guidance.

Changes

Worktree list documentation

Layer / File(s)	Summary
Document selection and metadata-only listing docs/advanced_usage.md	Documents explicit and implicit set selection, all-set listing, metadata-only output, recursive discovery, and related errors and warnings. It also covers plugin list selection, bounded traversal, and polling guidance.

Priority: ⬇️ Low

Estimated code review effort: 1 (Trivial) | ~3 minutes

Change: Other

Merge Risk: ⚪ Minimal · up to 9ecf9

The documented worktree-list behavior is ready to merge.

Pre-merge checks: 5

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly identifies documentation for contextual, metadata-only worktree listing, which matches the main change.
Docstring Coverage		No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0 files. (1 skipped: 1 unsupported.)

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

_{A rabbit reads the worktree guide,
And finds each set with care.
Metadata paths unfold,
No Git probes tread the trail,
Warnings mark what cannot be found,
Then off it hops with flair.}

_{Comment @coderabbitai help to get the list of available commands.}