#502 Atomic agent work selection, dependency integrity, and recovery primitives

Summary

• add SDK-backed pm claim --next with bounded atomic conflict retries and --if-available
• make pm next caller-aware, remove recommendation duplication, and preserve lifecycle/dangling blockers
• validate dangling parent/blocker/dependency references with actionable remediation
• make recovery suggestions arity-aware and accept token-efficient comments --body / --comment aliases
• update completions, contracts, SDK context evaluation, docs, generated changelog, and Sentry expected-handled telemetry classification

PM lineage

Closes pm-114v, pm-l0bu, pm-yl6c, pm-hfg5, pm-ol5v, pm-6y58, pm-z32q, and regression follow-up pm-w7jq.

Verification

• pnpm release:gates through build, typecheck, static/docstring ratchets, docs, context evaluation, security, 100/100/100/100 coverage, packed smoke, and 88-command package dogfood
• 5,524 tests at 100% statements/branches/functions/lines
• isolated installed-tarball acceptance: init, create, atomic claim-next, comments body alias, dangling-reference validation, SDK import
• live Sentry/telemetry: zero blocking critical/high issues, 0.34% finish error rate, zero failures missing error codes
• pm health --check-only --summary: all checks green; history drift zero across 1,709 items
• pnpm changelog:pm:check

The committed Greptile gate identified an invalid synthetic dependency kind in one test; follow-up commit 4ed719c0 corrects it and proves two distinct dangling references are retained.

---

Summary by cubic

Adds atomic work selection for agents and hardens dependency integrity across recommendation, claim, and validate. pm claim --next now atomically selects and claims the next caller-available item; pm next is caller-aware, non-duplicating, and treats dangling references as blockers.

• New Features

  • pm claim --next: atomic recommend+claim with bounded retries. Honors --if-available across candidates, aligns --author with ranking, enforces id/--next XOR, and returns the recommendation + attempt count; zsh completions wired.
  • pm next: excludes the recommended item from ready, reports foreign-owned work in held_by_others, and uses the same ranking data the SDK exposes.

• Bug Fixes

  • Validation: new dependency_references check warns on dangling parent, blocked_by, and dependency ids with clear, parent-specific remediation; actionability and pm next treat them as unresolved blockers (no silent unblocks).
  • Recovery/UX: suggested retry is arity-aware (boolean flags render without a placeholder). pm comments accepts hidden --body and --comment aliases for --add; completions, contracts, and docs updated.
  • Recommendation: fixed pm next blocked summary and companion so counts and rows reflect lifecycle and dependency state.
  • Telemetry: Sentry gate now classifies starter search/context tracker-initialization errors as expected handled.