Parcel Roster

Parcel Roster

The across-the-board view of active parcel worktrees. Answers: what parcels are in flight, what state are they in, and which ones are ready for audit or merge?

Bundled with rookery. Pairs with rookery worktree list (the lower-level CLI view) and rookery status / rookery land history (history-side views). This skill is the agent-friendly markdown analogue.

Mirrors lane-roster but targets the parcel tree (the configured worktrees root) rather than the lane tree (.claude/worktrees/*). The two are separate — do not conflate them.

When to use

• Starting a wave-triage pass and needing a snapshot of the fleet
• Asking "what's ready to merge?" after a wave of parallel builds
• Deciding whether a parcel is still in flight, done but unaudited, or audited-and-waiting
• Before authoring a new parcel, to see which ids are already taken

When NOT to use

• You want lane sessions (.claude/worktrees/) — use lane-roster instead
• You want detailed verdicts per parcel — use parcel-audit
• You want merge-order decisions — use wave-triage

Path resolution (read this once per session)

This skill operates on parcel worktrees that live under a configurable root. Resolve <worktrees_root> once, in this order:

1. rookery.yaml in CWD: read the worktrees_root key (top-level). Use this if present and non-empty.
2. ROOKERY_WORKTREES env var: fall back to this if step 1 yielded nothing.
3. Default: ./worktrees (relative to CWD).

The audits sibling lives at <worktrees_root>/audits/.

Workflow

Step 1 — Enumerate parcel worktrees

Resolve <worktrees_root> per the path-resolution block above. Iterate directory entries under <worktrees_root>/ (Bash for-loop over */, or Glob+filter). For each entry, include it only if both are true:

1. It is a directory (skip loose files — real fleets have *.pid, *.iter, and occasional log files at top level that are NOT worktrees)
2. It contains a .git file or directory (real worktrees always do; Glob alone can't confirm)

Special-case dirs to skip by name: audits/, logs/, smoke-runs/. These are sibling artefact roots, not worktrees. Extending this blacklist is cheap — prefer the .git presence check as the authoritative filter.

If the Glob returns nothing, emit:

STATUS: no parcel worktrees found
ROOT: <worktrees_root>

and stop. An empty tree is a valid answer.

Step 2 — Per-worktree git state

For each candidate <wt>:

git -C <wt> branch --show-current
git -C <wt> log --oneline -1
git -C <wt> rev-list --count main..HEAD   # commits ahead
git -C <wt> rev-list --count HEAD..main   # commits behind
git -C <wt> status --porcelain | wc -l    # dirty count
git -C <wt> stash list | wc -l            # stash count

Use git -C <path> — never cd. If any command errors (e.g. the dir is not a git worktree, or main no longer exists), record the error verbatim in that row's error column and move on. Do not abort the whole roster on one bad worktree.

Step 3 — Check completion + audit markers

For each <wt>, check file presence via Glob (not Bash ls):

• <wt>/PARCEL_DONE.md — the parcel's own completion report
• <worktrees_root>/audits/<id>.v*.md — audit files (zero or more; record the highest version present)

Where <id> is the worktree directory name.

Step 4 — Emit the table

Produce a markdown table sorted by parcel id (alphanumeric, so I1 < I2 < P1 < P10 < P2 unless a natural-sort is explicitly requested). One row per worktree:

| id | branch | ahead | behind | dirty | stash | DONE? | audit | last-commit |
|----|--------|-------|--------|-------|-------|-------|-------|-------------|
| I1 | parcel/I1-merge | 4 | 0 | 0 | 0 | ✓ | v2 | ab7502d fix(...) |
| I2 | parcel/I2-wire  | 1 | 0 | 3 | 0 | ✗ | —  | 72a2e29 feat(...) |

• DONE?: ✓ if PARCEL_DONE.md exists, ✗ if not
• audit: highest version present (e.g. v1, v2), or — if none
• last-commit: short hash + subject, truncated to fit

Below the table, emit a one-line fleet summary:

FLEET: <total> parcels, <done-count> DONE, <audited-count> audited, <at-risk> at-risk (dirty or no-DONE-after-N-commits)

Step 5 — Flag at-risk and absorbed parcels

A parcel is at-risk if any of:

• dirty > 0 (uncommitted work that could be lost)
• ahead > 0 and no PARCEL_DONE.md and no commit in the last 2 hours (stalled mid-build)

A parcel is absorbed if:

• ahead == 0 AND behind >> 0 (e.g. behind ≥ 50) AND PARCEL_DONE is present

Absorbed parcels have shipped their work through main via rebase or squash; the branch is now a stale historical pointer. In practice this is the most common end state for a merged wave — operators should know the parcel is "done, not lost" so they can cleanly garbage-collect worktrees.

A parcel is fresh if ahead > 0 (still has unmerged commits) OR behind is small (close to main).

List at-risk rows separately below the main table. Mark absorbed rows with a distinct marker (e.g. trailing (absorbed)) so they do not confuse with in-flight parcels. Do not attempt to fix or prune — branch / worktree deletion is a separate concern (rookery worktree).

Hard rules

Anti-patterns

See also

• lane-roster — the analogue for lane worktrees under .claude/worktrees/
• parcel-reader — parses a single PARCEL_DONE.md into structured sections
• parcel-audit — produces a verdict for one parcel
• wave-triage — consumes this roster + audits to compute merge order
• rookery worktree list / rookery status — CLI views of the same fleet