Add ranked atomic agent work selection primitives

Merged
UN
4mo ago
+1099-121

Summary

  • expose filtered, bounded claimNext() through the public SDK, MCP action schema, and CLI
  • keep pm next recommendation and ready tail in one stable ranked sequence with explicit one-based ranks
  • separate human-gated Decisions into decision_needed, with explicit maintainer opt-in for claiming
  • return a non-error empty --if-available envelope when a worker lane is exhausted
  • update completions, contracts, docs, generated contract snapshot, and package-owned changelog

pm tracker items

  • pm-fjxm — filtered bounded atomic claim-next walking and exhaustion semantics
  • pm-1mwk — ranked ready continuation
  • pm-eqk0 — human-gated decision separation

Verification

  • node scripts/run-tests.mjs coverage — 5,550/5,550; 100% statements/branches/functions/lines
  • pnpm lint — ESLint, zero jscpd clones, static-quality/docstring/token gates
  • pnpm contracts:check
  • pnpm quality:docs-skills
  • pnpm security:scan
  • pnpm audit --audit-level moderate
  • fresh packed-package install in an isolated workspace proved filtered rank-1 selection and bounded atomic claim

Closes #509
Closes #513

Summary by Sourcery

Add ranked atomic next-work claiming with bounded candidate walks, expose it through the CLI, SDK, and MCP contracts, and refine next-work queues to separate human-gated decisions from agent-ready items.

New Features:

  • Introduce CLI and SDK support for claim --next / claimNext() using next-work filters and bounded ranked candidate selection.
  • Expose one-based ranks on next-work actionable items and surface a separate decision_needed queue for human-gated decisions.

Bug Fixes:

  • Treat exhaustion of claim --next --if-available as a deliberate non-error empty result instead of throwing, enabling contention-tolerant worker loops.
  • Align pm next / claim --next behavior with documentation by keeping ready items in stable recommendation order and excluding human-gated Decision records from agent lanes by default.

Enhancements:

  • Extend pm next and related rendering to show explicit ranks, support optional inclusion of decision items, and document the updated semantics in SDK and command docs.
  • Update MCP action schemas and CLI contracts for claim to support both item-id and next-work based invocation, along with new filters and bounds.
  • Tighten validation around --max-attempts for claim-next candidate walks to enforce safe, bounded ranges.

Documentation:

  • Refresh SDK and command documentation to describe ranked next-work queues, decision separation, new claim-next filters, and exhaustion semantics.

Tests:

  • Expand unit tests for claim-next, next-work ranking, markdown rendering, SDK entrypoints, and CLI registration to cover the new filters, ranks, decision partitioning, and empty-claim behavior.

Chores:

  • Update generated contracts snapshot, agent issue history, and changelog entries to track the new ranked claim-next behavior and decision handling fixes.

Summary by cubic

Adds ranked, atomic next-work selection so agents can safely claim the next item in a stable order across the CLI, SDK, and MCP. Speeds up CI by sharding coverage and removing the test fixture spawn tax while keeping the 100% coverage gate, and hardens coverage by disabling persisted checkout credentials.

  • New Features

    • CLI: pm claim --next accepts pm next filters (--type, --tag, --priority, --assignee-filter, --parent, --sprint, --release), adds --max-attempts (1–100) and --include-decisions; with --if-available returns an empty envelope on exhaustion; completions updated.
    • SDK/MCP: PmClient.claimNext() and top-level claimNext() expose the same filtered, bounded selection; schemas enforce one-of id|next with a next=true discriminator, validate maxAttempts, accept numeric priorities, and publish the full claim-next surface.

  • Bug Fixes

    • GH-509/513: Keep the ready queue in recommendation order with one-based rank, thread next-work filters to claim --next, walk ranked candidates on race loss, and standardize no_available_next_item.
    • Contracts/CLI: Honor explicit author affinity, keep Decision items out of agent lanes by default and exclusive across ready/held_by_others, resolve claimant identity defaults, distinguish zero-match candidate errors from exhaustion, and align strict SDK/MCP schemas.
    • CI/CLI: Disable persisted checkout credentials in coverage jobs and lock it in the workflow contract; complete claim-next completions with dynamic type/tag choices to match pm next.