fix(beads): use native --ready filter instead of empty status:ready label

[trillium]

Intent

Fix a verified bug in firstmate's beads backlog backend: the ready-query used an empty label instead of bd's native ready filter, so the backlog rendered empty against the live store. Scout evidence (task-oec6): bin/fm-session-start.sh ran 'task list --label "status:ready"' which returned 0 items against the live ~/data/tasks/.beads store, while 'task list --ready' returns 255+ genuinely-ready items (267 verified live). Fix: switched the beads-backend ready path in bin/fm-session-start.sh from the --label "status:ready" query to bd's native dependency-derived --ready filter, preserving $BACKLOG_LIMIT and output shape. Also found and fixed a second spot assuming the same broken status:ready label: bin/fm-teardown.sh's post-completion beads prompt text, updated to reference 'task list --ready' instead. Updated docs/configuration.md (~line 46) to describe the corrected --ready behavior instead of the broken status:ready-label design. Added a test in tests/fm-session-start.test.sh (test_backlog_compact_beads_uses_ready_filter_not_empty_label) with a fake task CLI fixture asserting the session digest invokes 'list --ready --limit 80' and renders its output, not the empty label query. Deliberately out of scope, noted but not implemented: decision-holds are unsupported on the beads backend - that is a separate follow-up. Constraint: kept the change minimal since the beads-backend code came from PR #7 already on origin/main; branched from current origin/main.

What Changed

• bin/fm-session-start.sh: switched the beads-backend ready-query from task list --label "status:ready" (a label that doesn't exist, so it always returned 0 items) to bd's native dependency-derived --ready filter, preserving $BACKLOG_LIMIT and the existing output shape.
• bin/fm-teardown.sh: updated the post-completion beads reminder text to reference task list --ready instead of the broken status:ready label.
• docs/configuration.md: corrected the beads backend description to document the --ready filter behavior instead of the broken label-based design.
• tests/fm-session-start.test.sh: added test_backlog_compact_beads_uses_ready_filter_not_empty_label, a regression test with a fake task CLI fixture asserting the session digest invokes list --ready --limit 80 and renders its output.

Risk Assessment

✅ Low: Minimal, well-scoped one-line functional fix (label query → native --ready filter) plus consistent doc/reminder text updates and a regression test asserting the exact invocation; no other stale status:ready references remain.

Testing

Ran the fm-session-start test suite (29/29 pass, including the new fixture-based regression test) and additionally reproduced the original bug and fix live against the real ~/data/tasks/.beads store: the old status:ready-label query returns 0 items while the fixed --ready query returns 267 ready items, matching the scout's reported evidence; the teardown script's companion text fix was confirmed by direct inspection since no test exercises that specific string.

Evidence: Live beads store: broken status:ready label query vs fixed --ready query

=== OLD broken query: task list --label "status:ready" (pre-fix behavior) ===
No issues found.

=== NEW fixed query: task list --ready --limit 80 (bin/fm-session-start.sh at fadf39b) ===
○ task-ces4 ● P1 Crew escalation-3: default to auto-recovery (exit+restart) instead of asking captain (robots-75zz)
○ task-h5q ● P1 Event stream & webhook ingestion — external events into agent context
○ task-0q0 ● P2 Research beads-in-repos integration models with PAI brain + observability
○ task-0rq ● P2 Resume builder restructure — agent-driven achievement collection
○ task-0t1r ● P2 Test bead for full lifecycle
○ task-21p ● P2 speak: harden pause/resume against PortAudio mid-write race
○ task-2gx ● P2  Hydrogen-Sonata-playing… -- these claude code shimmery things - find where they live so we can cull them down
○ task-35ww ● P2 Implement graceful agent shutdown via parlay with retro
○ task-37p ● P2 cursorless-css-state: implement serverless GIF generation on Vercel
○ task-3cc ● P2 Build Mayor discernment hook — model selection guidance per task complexity
○ task-4my ● P2 Location tracking & drive time — Home Assistant + Tesla API → auto drive time entries
○ task-5is ● P2 Deprecate pai-bridge auto-commit on mini2 (mirrors MacBook decision-fhi)
○ task-5qj ● P2 PAI personal agent infrastructure — distributable Gas City pack
○ task-6ce ● P2 Melanie's website — WordPress to Next.js full migration
○ task-6uy ● P2  the claude code hints - find where they live so we can cull them down
○ task-7g3g ● P2 Convert 12 GIVEN/WHEN/THEN scenarios to formal test cases and BDD specs
○ task-7y1 ● P2 Recruiter & job tracking — person entries in Beads, agents log silently
○ task-89m ● P2 speak: heal stale audio stream after sleep/wake and device changes
○ task-8dn ● P2 Awesome-Talon autonomous discovery pipeline — local inference processes Talon repos
○ task-8kqj ● P2 trilliumsmith.com: add contact CTA at top and bottom
○ task-8mt ● P2 Resume store design — federated brain stores for resume atoms
○ task-8oxt ● P2 Implement idle-task-discovery in watcher: when fleet is idle and wake fires, evaluate task store for new work
○ task-8yi ● P2 Re-screenshot /status/ light + /plans/ after display wake (ISA brain-8u7xv ISC-19/20)
○ task-9ebw ● P2 Multi-phase self-healing render validation for Herdr spatial layout

Phase 1: Validators + diagnostics logging (in progress)
Phase 2: 4-tier fallback system + terminal detection
Phase 3: Tier caching + capability detection
Phase 4-6: Health checks, dashboard, comprehensive testing

Goal: Detect render issues at runtime, auto-fallback gracefully, provide dev diagnostics
○ task-9g4 ● P2 Wire monitor step into parrot_tester Talon UI
○ task-9q7 ● P2 [bug] Fix context percentage indicator — shows stale/false values
○ task-9y23 ● P2 Implement firstmate feedback on wake usefulness
○ task-a1w2 ● P2 Implement staleness metrics and action flags on watcher wake
○ task-aes ● P2 Job application workflow — full pipeline design
○ task-ay0 ● P2 gascity: progname/monolith fast suite red — ratchet over threshold + env flakes
○ task-ben ● P2 Parrot training — decouple UI from training engine, Talon UI as frontend
○ task-bg73 ● P2 GitHub profile: add contact CTA at top and bottom
○ task-bom ● P2 Fill brain-eegw7 body — Touchless iOS cursorless delivery (architecture/testing/UI verification)
○ task-c5c ● P2 Tiny Keyboard App Store readiness — robustness, Swift tests, submission, settings panel
○ task-cea ● P2 resolve beads.role git config from BEADS_DIR not CWD
○ task-cfzs ● P2 Resume: audit bullets for impact-first framing
○ task-crn ● P2 cv-generator: standing losslessness regression test (Dolt-history backed)
○ task-cwef ● P2 merge beads Releases v1.1.2
○ task-ddv ● P2 Brain/Beads migration plan — PAI memory, GasCity, résumé all wiring into brain substrate
○ task-dzux ● P2 Test bead for lifecycle labels
○ task-ecl ● P2 Migrate Pulse to a design system: components/ui manifest + hook enforcement (seed from massage)
○ task-enii ● P2 Implement GitHub PR feedback → agent notification via parlay
○ task-ffxl ● P2 LinkedIn: add cal.com CTA at top and bottom
○ task-ft4n ● P2 GitHub: improve folder structure
○ task-g68b ● P2 Build agentic-generic out as a full standalone resume
○ task-ghh ● P2 Migrate Feed System from Cloudflare Workers to local mini2 daemon
○ task-gl3 ● P2 GithubActivityTriage.ts — triage recent GitHub events into brain project beads
○ task-gqz ● P2 FeedTack simplify & streamline — UX polish, code simplification, supply data enrichment
○ task-gsy ● P2 Define the 'last contacted' recency signal source for staleness checks — call history / iMessage / email / Toastmasters attendance — since rvs finds where numbers live, not when a contact was last reached
○ task-h5ux ● P2 Discover gascity cross-machine agent spawning capabilities
○ task-h7r ● P2 Mayor agent architecture — GasCity integration, personality-bead loading, decision logging
○ task-lehj ● P2 Search and document all GWT (Given-When-Then) enforcement scenarios from recent context
○ task-ll97 ● P2 Implement robots ticket filing on system action failures
○ task-m4q ● P2 Inbox scoping workflow — auto-elaborate new task and idea beads
○ task-m6r ● P2 Mirror 2026-07-06 harness lean-up onto mini2
○ task-m9cv ● P2 Resume: remove Bluesky link
○ task-obhu ● P2 Merge firstmate upstream after beads-backlog-backend PR lands and merges
○ task-oosv ● P2 Implement proactive idle agent shutdown at 50-60m
○ task-pas ● P2 design: replace cv-generator yml/manifest with federated brain stores
○ task-pky ● P2 Agent contract enforcement: PostToolUse[Agent] check for declared output contracts
○ task-q1k8 ● P2 Implement perpetual-delegation pattern for ambiguous task requests
○ task-q5kx ● P2 Integrate /afk (away-mode) with task store and parlay for autonomous work during captain sleep
○ task-qg62 ● P2 Implement Rango CLI via HTTP Bridge
○ task-qjwc ● P2 Verify parlay-spawn is the spawn method and enable spawning under account2 (acc2) to spread Claude usage across accounts
○ task-ql5m ● P2 LinkedIn: audit outbound links route to portfolio (and back)
○ task-qpr ● P2 Resume pipeline architecture — full end-to-end design
○ task-tbzw ● P2 GWT Enforcement Scenarios: Central tracking and implementation status
○ task-u47t ● P2 OpenSuperWhisper: switch input mic live without restart
○ task-ul9a ● P2 herdr-web: code quality review — UI consolidation (filter pills, cmd+click, styles)
○ task-vy2u ● P2 Push 10 gated pai-hooks commits to origin/main
○ task-xmby ● P2 Test bead for full lifecycle
○ task-y5o ● P2 Pulse page: recent beads feed across all federated brain stores
○ task-y69 ● P2 Apply colocated/corrected contact data to both platforms using the granular CRUD — dedupe and update each contact per the compiled sources (the payoff step the rvs/ddw research feeds into)
○ task-y8ii ● P2 Implement agent parlay enrollment — MUST be first action on spawn
○ task-ypmg ● P2 Create durable firstmate relaunch daemon that launches via parlay
○ task-yxz ● P2 Massage site roadmap — print layout, Instagram, config refactor, Stripe, multitenant
○ task-z567 ● P2 Implement turn-end guards with captain accountability checkpoints
○ task-zkz0 ● P2 Implement robots-done → agent notification via parlay
○ task-znsm ● P2 Chat server on :31337 returns 404 to everyone (relay included) — component mounting /api/chat/* is down, not the relay. Find whether Pulse or a standalone parlay server owns those routes; decouple the parlay server from PAI and run it as a standalone Go process.
○ task-ouhq ● P3 Update no-mistakes to v1.41.2

--------------------------------------------------------------------------------
Total: 80 issues (80 open, 0 in progress)

Status: ○ open  ◐ in_progress  ● blocked  ✓ closed  ❄ deferred

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

✅ **Review** - passed

✅ No issues found.

✅ **Test** - passed

✅ No issues found.

• bash tests/fm-session-start.test.sh — all 29 tests pass, including the new test_backlog_compact_beads_uses_ready_filter_not_empty_label regression test
• Manual: ran task list --label "status:ready" --limit 80 against the live ~/data/tasks/.beads store — returned 'No issues found.' (0 items), reproducing the reported bug
• Manual: ran task list --ready --limit 80 against the same live store — returned 267 genuinely-ready items, confirming the fix
• Manual: extracted and ran the exact print_backlog_beads_compact function body from bin/fm-session-start.sh (target commit) against the live store — rendered a populated, correctly-formatted compact backlog listing
• Code inspection: confirmed bin/fm-teardown.sh's post-completion beads reminder text now says 'Run task list --ready' instead of referencing the broken status:ready label
• Code inspection: confirmed docs/configuration.md describes the corrected --ready behavior

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.

Summary by CodeRabbit

• Bug Fixes

  • Backlog views now use the native ready-task query, ensuring dependency-ready tasks appear correctly.
  • Removed reliance on obsolete status:ready labels.
  • Updated completion reminders and configuration guidance to reflect the improved workflow.

• Tests

  • Added regression coverage confirming ready tasks are shown and empty fallback results are avoided.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 5e4078cb-05dd-4d46-a7a3-d4156b64fbef

📥 Commits

Reviewing files that changed from the base of the PR and between cb69726 and fadf39b.

📒 Files selected for processing (4)

• bin/fm-session-start.sh
• bin/fm-teardown.sh
• docs/configuration.md
• tests/fm-session-start.test.sh

---

📝 Walkthrough

Walkthrough

The Beads backlog flow now uses task list --ready for dependency-derived ready tasks. The teardown reminder and configuration documentation use the same command. Tests add a fake CLI fixture and verify the query, limit, and output.

Changes

Beads ready-task backlog

Layer / File(s)	Summary
Native ready-task selection and guidance bin/fm-session-start.sh, bin/fm-teardown.sh, docs/configuration.md	The backlog query, completion reminder, and documentation now use task list --ready instead of status:ready.
Regression coverage tests/fm-session-start.test.sh	The fake Beads CLI and regression test verify ready-task output, --limit 80, and rejection of the obsolete label query.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• trillium/firstmate#11: Both changes update Beads backlog readiness handling in session workflows.

Suggested reviewers: kunchenguid

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely identifies the main change: replacing the empty status:ready label query with the native --ready filter.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fm/beads-ready-query-fm-session-start-beads-backend-ready-que-c8

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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