Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
unbraind merged 3 commits into from
Jul 10, 2026
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
3122405
feat(pm): ship atomic agent work selection and integrity primitives
unbraind Jul 10, 2026
4ed719c
test(validate): prove multiple dangling references are retained
unbraind Jul 10, 2026
378dc96
fix(claim): honor atomic selection contracts from review
unbraind Jul 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .agents/pm/extensions/.managed-extensions.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"version": 1,
"updated_at": "2026-07-10T13:19:14.505Z",
"updated_at": "2026-07-10T21:12:15.248Z",
"entries": [
{
"name": "pm-changelog",
Expand Down
26 changes: 21 additions & 5 deletions .agents/pm/features/pm-114v.toon
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,20 +2,36 @@ id: pm-114v
title: "pm claim --next: atomically claim the next actionable item so parallel agents each get distinct work"
description: "Companion to pm-8t5x. pm next + pm claim as separate steps race under parallel agents: all N agents get the same recommendation and N-1 fail their claim. Add an atomic recommend+claim with bounded retry over next-ranked candidates so each parallel agent receives a distinct item. Idea originated in the 2026-07-03 concurrency review (recorded inside pm-8t5x's fix sketch); promoted to its own tracked Feature by the 2026-07-04 metadata review."
type: Feature
status: open
status: closed
priority: 2
tags[3]: agent-ux,cli,concurrency
created_at: "2026-07-04T19:20:15.349Z"
updated_at: "2026-07-10T16:50:47.380Z"
updated_at: "2026-07-10T21:11:59.596Z"
closed_at: "2026-07-10T21:11:58.702Z"
author: maintainer-agent
estimated_minutes: 240
acceptance_criteria: "pm claim --next claims a distinct item per parallel agent (stress-verified, zero double-grants); bounded candidate retry on already_claimed_by; output includes pm next rationale; wired across MCP/contracts/completion/docs per new-command checklist"
parent: pm-dj98
risk: medium
confidence: medium
dependencies[2]{id,kind,created_at,author,source_kind}:
resolution: Added atomic ranked claim-next selection with bounded conflict retries and if-available behavior.
expected_result: Parallel agents can claim distinct recommended work through the SDK-backed CLI without a list-then-claim race.
actual_result: "claim --next ranks actionable candidates, retries ownership conflicts, returns recommendation evidence, and passed concurrency and packed-install acceptance tests."
dependencies[1]{id,kind,created_at,author,source_kind}:
pm-2muu,related,"2026-07-05T04:07:28.566Z",claude-code-agent,null
pm-8t5x,blocked_by,"2026-07-05T04:07:28.566Z",claude-code-agent,null
comments[1]{created_at,author,text}:
comments[4]{created_at,author,text}:
"2026-07-10T16:50:47.379Z",maintainer-agent,"Unblocked as of 2026-07-10 verification: sole blocker pm-8t5x (atomic test-and-set claim) is closed, so the atomic substrate this command needs exists. Actionable now; pairs naturally with the parallel-agent work-distribution story and pm-yl6c/pm-hfg5 pm-next defects when scheduling."
"2026-07-10T17:51:48.842Z",codex-root,"Implementation start: active in the broad atomic work-selection and agent recovery PR. Live all-status duplicate check, full item metadata, closed prerequisite lineage, GitHub issues, security alerts, dependency audit, release state, and Sentry issue surface were reviewed before claiming. This item shares CLI/SDK contracts, recovery envelopes, and end-to-end verification with the seven sibling items in the bundle."
"2026-07-10T20:32:29.986Z",codex-wide-pm-sdk,"Verification: pnpm release:gates passed build/typecheck/static/docstring ratchets/docs/context/security, 100/100/100/100 coverage with 5,524 tests, packed npx smoke, and 88-command package dogfood; isolated installed-tarball acceptance created two items, atomically claimed one, accepted comments --body, detected one dangling dependency, and imported PmClient. Live Sentry/telemetry: 0 blocking critical/high, 0.34% finish error rate, zero missing error-code rows. pm health: all 7 checks ok; history drift: 0 across 1,709 items."
"2026-07-10T21:11:56.435Z",codex-wide-pm-sdk,"Review evidence: fixed all claim-next findings. --if-available now advances skipped held candidates and returns a non-failing skip only when all are held; explicit --author controls both ranking and mutation; id plus --next is rejected; zsh flags moved from update to claim. Focused suites passed and full coverage is 100/100/100/100 with 5,528 tests."
files[3]{path,scope,note}:
src/cli/commands/claim.ts,project,atomic ranked claim composition
src/cli/commands/next.ts,project,shared agent work-selection envelope
src/core/item/actionability.ts,project,shared dependency-aware readiness primitive
tests[1]{command,scope,timeout_seconds}:
node scripts/run-tests.mjs test -- tests/unit/commands/claim-command.spec.ts tests/unit/commands/next-command.spec.ts,project,300
docs[2]{path,scope,note}:
docs/COMMANDS.md,project,agent-facing command contract
docs/SDK.md,project,SDK context primitive contract
close_reason: "Addressed Greptile and CodeRabbit claim-next contract, author, XOR, and completion findings with full coverage."
body: "## Context\nSplit out of pm-8t5x (claim test-and-set): once claim correctly CONFLICTs on held items, N parallel agents that each run `pm next` will all be recommended the SAME top item, all try to claim it, and N-1 will bounce. The missing primitive is an atomic \"give me my own item\".\n\n## Design sketch\n`pm claim --next` (or `pm next --claim`): compute the pm next recommendation and claim it in one operation; on already_claimed_by conflict, retry with the next-ranked candidate (bounded, e.g. 10 candidates) until one claim succeeds; return the claimed item with the same rationale payload pm next emits. Honors --if-available semantics naturally (skip held candidates instead of erroring). Requires pm-8t5x semantics (deps: blocked_by) and benefits from pm-2muu's lock wait.\n\n## Definition of done\nN-parallel `pm claim --next` stress: N distinct items claimed, zero double-grants; recommendation rationale preserved in output; MCP action + contracts + completion + docs wired per the new-command checklist (grep replicate every site); spec covers conflict-retry and exhausted-candidates paths."
18 changes: 18 additions & 0 deletions .agents/pm/history/pm-114v.jsonl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,3 +4,21 @@
{"ts":"2026-07-05T04:07:28.609Z","author":"claude-code-agent","op":"update","patch":[{"op":"add","path":"/metadata/dependencies/1/author","value":"claude-code-agent"},{"op":"replace","path":"/metadata/dependencies/1/created_at","value":"2026-07-05T04:07:28.566Z"},{"op":"replace","path":"/metadata/dependencies/1/kind","value":"blocked_by"},{"op":"replace","path":"/metadata/dependencies/1/id","value":"pm-8t5x"},{"op":"add","path":"/metadata/dependencies/0/author","value":"claude-code-agent"},{"op":"replace","path":"/metadata/dependencies/0/created_at","value":"2026-07-05T04:07:28.566Z"},{"op":"replace","path":"/metadata/dependencies/0/id","value":"pm-2muu"},{"op":"replace","path":"/metadata/updated_at","value":"2026-07-05T04:07:28.609Z"}],"before_hash":"8bb172bb0b813251ee16d36f68c062c029566bb5d7e907edab68a3cb5b24764d","after_hash":"08ef36d1ee7d87f0898884be76e90eba95c9cc00edcf52a3a1ab1a4a08445351","message":"Normalize dependency ids flagged by PR review"}
{"ts":"2026-07-07T14:17:46.978Z","author":"maintainer-agent","op":"update","patch":[{"op":"replace","path":"/metadata/updated_at","value":"2026-07-07T14:17:46.978Z"},{"op":"replace","path":"/metadata/description","value":"Companion to pm-8t5x. pm next + pm claim as separate steps race under parallel agents: all N agents get the same recommendation and N-1 fail their claim. Add an atomic recommend+claim with bounded retry over next-ranked candidates so each parallel agent receives a distinct item. Idea originated in the 2026-07-03 concurrency review (recorded inside pm-8t5x's fix sketch); promoted to its own tracked Feature by the 2026-07-04 metadata review."}],"before_hash":"08ef36d1ee7d87f0898884be76e90eba95c9cc00edcf52a3a1ab1a4a08445351","after_hash":"68cce739c3c22f1046d7efcc58004263ae26b1725344ac5bb200c7e66e127e39"}
{"ts":"2026-07-10T16:50:47.380Z","author":"maintainer-agent","op":"comment_add","patch":[{"op":"replace","path":"/metadata/updated_at","value":"2026-07-10T16:50:47.380Z"},{"op":"add","path":"/metadata/comments","value":[{"created_at":"2026-07-10T16:50:47.379Z","author":"maintainer-agent","text":"Unblocked as of 2026-07-10 verification: sole blocker pm-8t5x (atomic test-and-set claim) is closed, so the atomic substrate this command needs exists. Actionable now; pairs naturally with the parallel-agent work-distribution story and pm-yl6c/pm-hfg5 pm-next defects when scheduling."}]}],"before_hash":"68cce739c3c22f1046d7efcc58004263ae26b1725344ac5bb200c7e66e127e39","after_hash":"15ff6239a51ad994b2dee0adabf04bf47aa66c312ef49afa63e129ce90d6dcbf"}
{"ts":"2026-07-10T17:51:46.622Z","author":"codex-root","op":"claim","patch":[{"op":"replace","path":"/metadata/updated_at","value":"2026-07-10T17:51:46.622Z"},{"op":"add","path":"/metadata/assignee","value":"codex-root"}],"before_hash":"15ff6239a51ad994b2dee0adabf04bf47aa66c312ef49afa63e129ce90d6dcbf","after_hash":"a423c135f2fa1a555abd038b682e06ce8debe3f89330e50acf9036ace070fed1"}
{"ts":"2026-07-10T17:51:47.558Z","author":"codex-root","op":"update","patch":[{"op":"replace","path":"/metadata/updated_at","value":"2026-07-10T17:51:47.558Z"},{"op":"replace","path":"/metadata/status","value":"in_progress"}],"before_hash":"a423c135f2fa1a555abd038b682e06ce8debe3f89330e50acf9036ace070fed1","after_hash":"1858cb0cd4a709ae0b093ad0ce20db5500467c76dad207d2083775de5d50b4d1","message":"Start broad atomic work-selection and agent recovery bundle; duplicate-safe all-status orientation complete"}
{"ts":"2026-07-10T17:51:48.843Z","author":"codex-root","op":"comment_add","patch":[{"op":"add","path":"/metadata/comments/1","value":{"created_at":"2026-07-10T17:51:48.842Z","author":"codex-root","text":"Implementation start: active in the broad atomic work-selection and agent recovery PR. Live all-status duplicate check, full item metadata, closed prerequisite lineage, GitHub issues, security alerts, dependency audit, release state, and Sentry issue surface were reviewed before claiming. This item shares CLI/SDK contracts, recovery envelopes, and end-to-end verification with the seven sibling items in the bundle."}},{"op":"replace","path":"/metadata/updated_at","value":"2026-07-10T17:51:48.843Z"}],"before_hash":"1858cb0cd4a709ae0b093ad0ce20db5500467c76dad207d2083775de5d50b4d1","after_hash":"8e5746a5411d366199d00986936e01d80b4eca426fa95dee663ec1a7c640b1d3"}
{"ts":"2026-07-10T18:08:23.012Z","author":"codex-root","op":"files_add","patch":[{"op":"replace","path":"/metadata/updated_at","value":"2026-07-10T18:08:23.012Z"},{"op":"add","path":"/metadata/files","value":[{"path":"src/cli/commands/next.ts","scope":"project","note":"shared agent work-selection envelope"}]}],"before_hash":"8e5746a5411d366199d00986936e01d80b4eca426fa95dee663ec1a7c640b1d3","after_hash":"2a547a46d3c62ad2fa282329971c9ba8e5d71ea20b13411144858c75c05c0a98"}
{"ts":"2026-07-10T18:08:23.460Z","author":"codex-root","op":"files_add","patch":[{"op":"add","path":"/metadata/files/1","value":{"path":"src/core/item/actionability.ts","scope":"project","note":"shared dependency-aware readiness primitive"}},{"op":"replace","path":"/metadata/updated_at","value":"2026-07-10T18:08:23.460Z"}],"before_hash":"2a547a46d3c62ad2fa282329971c9ba8e5d71ea20b13411144858c75c05c0a98","after_hash":"532dd78e8b1e3d97ade94733d410d547986438c8ab24b2c555ba95c8861f356b"}
{"ts":"2026-07-10T18:08:23.972Z","author":"codex-root","op":"docs_add","patch":[{"op":"replace","path":"/metadata/updated_at","value":"2026-07-10T18:08:23.972Z"},{"op":"add","path":"/metadata/docs","value":[{"path":"docs/COMMANDS.md","scope":"project","note":"agent-facing command contract"}]}],"before_hash":"532dd78e8b1e3d97ade94733d410d547986438c8ab24b2c555ba95c8861f356b","after_hash":"2f1bef1f0e79123898ff157057600bc3d9431082de8c286568136e6ff0c57093"}
{"ts":"2026-07-10T18:08:24.409Z","author":"codex-root","op":"docs_add","patch":[{"op":"add","path":"/metadata/docs/1","value":{"path":"docs/SDK.md","scope":"project","note":"SDK context primitive contract"}},{"op":"replace","path":"/metadata/updated_at","value":"2026-07-10T18:08:24.409Z"}],"before_hash":"2f1bef1f0e79123898ff157057600bc3d9431082de8c286568136e6ff0c57093","after_hash":"7986ae7713e5e44eb8a179e7be656a48111da7114d4da6f12f1a7447397da3f1"}
{"ts":"2026-07-10T18:08:38.110Z","author":"codex-root","op":"files_add","patch":[{"op":"replace","path":"/metadata/files/1/note","value":"shared agent work-selection envelope"},{"op":"replace","path":"/metadata/files/1/path","value":"src/cli/commands/next.ts"},{"op":"replace","path":"/metadata/files/0/note","value":"atomic ranked claim composition"},{"op":"replace","path":"/metadata/files/0/path","value":"src/cli/commands/claim.ts"},{"op":"add","path":"/metadata/files/2","value":{"path":"src/core/item/actionability.ts","scope":"project","note":"shared dependency-aware readiness primitive"}},{"op":"replace","path":"/metadata/updated_at","value":"2026-07-10T18:08:38.110Z"}],"before_hash":"7986ae7713e5e44eb8a179e7be656a48111da7114d4da6f12f1a7447397da3f1","after_hash":"fb30d1c384cb82ddd8ac31d904349c24e22b696ab1536f81e9e532ac7f27d4f4"}
{"ts":"2026-07-10T18:08:38.646Z","author":"codex-root","op":"tests_add","patch":[{"op":"replace","path":"/metadata/updated_at","value":"2026-07-10T18:08:38.646Z"},{"op":"add","path":"/metadata/tests","value":[{"command":"node scripts/run-tests.mjs test -- tests/unit/commands/claim-command.spec.ts tests/unit/commands/next-command.spec.ts","scope":"project","timeout_seconds":300}]}],"before_hash":"fb30d1c384cb82ddd8ac31d904349c24e22b696ab1536f81e9e532ac7f27d4f4","after_hash":"31d582d99c45979d6123409294c3a8fbc94b08f8be816c510a51042a272bebb8"}
{"ts":"2026-07-10T20:32:21.396Z","author":"codex-wide-pm-sdk","op":"update","patch":[{"op":"replace","path":"/metadata/updated_at","value":"2026-07-10T20:32:21.396Z"},{"op":"add","path":"/metadata/resolution","value":"Added atomic ranked claim-next selection with bounded conflict retries and if-available behavior."},{"op":"add","path":"/metadata/expected_result","value":"Parallel agents can claim distinct recommended work through the SDK-backed CLI without a list-then-claim race."},{"op":"add","path":"/metadata/actual_result","value":"claim --next ranks actionable candidates, retries ownership conflicts, returns recommendation evidence, and passed concurrency and packed-install acceptance tests."}],"before_hash":"31d582d99c45979d6123409294c3a8fbc94b08f8be816c510a51042a272bebb8","after_hash":"88310c52b838287bc4f162bb1193adcd9d0686d5b6794d09247834398f53c401","message":"Record implementation resolution"}
{"ts":"2026-07-10T20:32:29.987Z","author":"codex-wide-pm-sdk","op":"comment_add","patch":[{"op":"add","path":"/metadata/comments/2","value":{"created_at":"2026-07-10T20:32:29.986Z","author":"codex-wide-pm-sdk","text":"Verification: pnpm release:gates passed build/typecheck/static/docstring ratchets/docs/context/security, 100/100/100/100 coverage with 5,524 tests, packed npx smoke, and 88-command package dogfood; isolated installed-tarball acceptance created two items, atomically claimed one, accepted comments --body, detected one dangling dependency, and imported PmClient. Live Sentry/telemetry: 0 blocking critical/high, 0.34% finish error rate, zero missing error-code rows. pm health: all 7 checks ok; history drift: 0 across 1,709 items."}},{"op":"replace","path":"/metadata/updated_at","value":"2026-07-10T20:32:29.987Z"}],"before_hash":"88310c52b838287bc4f162bb1193adcd9d0686d5b6794d09247834398f53c401","after_hash":"74337624dcfe34a7ae884b3deddb33eb454cec920a0516606c84444fe8c0f7d6"}
{"ts":"2026-07-10T20:32:37.443Z","author":"codex-wide-pm-sdk","op":"close","patch":[{"op":"remove","path":"/metadata/dependencies/1"},{"op":"remove","path":"/metadata/assignee"},{"op":"replace","path":"/metadata/updated_at","value":"2026-07-10T20:32:37.443Z"},{"op":"replace","path":"/metadata/status","value":"closed"},{"op":"add","path":"/metadata/closed_at","value":"2026-07-10T20:32:37.437Z"},{"op":"add","path":"/metadata/close_reason","value":"Implemented and verified in the atomic work-selection, dependency-integrity, recovery, alias, and telemetry bundle."}],"before_hash":"74337624dcfe34a7ae884b3deddb33eb454cec920a0516606c84444fe8c0f7d6","after_hash":"657ed0dcf52e87cb135cd6376909ce9bf0a4c1a12dab6ba17b902dc6fc83bd3c"}
{"ts":"2026-07-10T20:32:38.402Z","author":"codex-wide-pm-sdk","op":"release","patch":[{"op":"replace","path":"/metadata/updated_at","value":"2026-07-10T20:32:38.402Z"}],"before_hash":"657ed0dcf52e87cb135cd6376909ce9bf0a4c1a12dab6ba17b902dc6fc83bd3c","after_hash":"60afee0e37905fd4da3c8040f6aec24c7d244b40bf8bef6a14712a957bd99ab4"}
{"ts":"2026-07-10T21:02:06.424Z","author":"codex-wide-pm-sdk","op":"update","patch":[{"op":"remove","path":"/metadata/close_reason"},{"op":"remove","path":"/metadata/closed_at"},{"op":"replace","path":"/metadata/updated_at","value":"2026-07-10T21:02:06.424Z"},{"op":"replace","path":"/metadata/status","value":"in_progress"}],"before_hash":"60afee0e37905fd4da3c8040f6aec24c7d244b40bf8bef6a14712a957bd99ab4","after_hash":"ea8d421a9b2a02856166191e00a3d323d0d32a311749f570e8173b4a9656579a","message":"PR review follow-up: honor claim-next if-available exhaustion, align --author selection, enforce id/--next XOR, and correct zsh claim completions."}
{"ts":"2026-07-10T21:02:07.092Z","author":"codex-wide-pm-sdk","op":"claim","patch":[{"op":"replace","path":"/metadata/updated_at","value":"2026-07-10T21:02:07.092Z"},{"op":"add","path":"/metadata/assignee","value":"codex-wide-pm-sdk"}],"before_hash":"ea8d421a9b2a02856166191e00a3d323d0d32a311749f570e8173b4a9656579a","after_hash":"9bce6bcfb67395bd6b176246e31905894b6cbf601338842a0ff52e4332aaee4d"}
{"ts":"2026-07-10T21:11:56.435Z","author":"codex-wide-pm-sdk","op":"comment_add","patch":[{"op":"add","path":"/metadata/comments/3","value":{"created_at":"2026-07-10T21:11:56.435Z","author":"codex-wide-pm-sdk","text":"Review evidence: fixed all claim-next findings. --if-available now advances skipped held candidates and returns a non-failing skip only when all are held; explicit --author controls both ranking and mutation; id plus --next is rejected; zsh flags moved from update to claim. Focused suites passed and full coverage is 100/100/100/100 with 5,528 tests."}},{"op":"replace","path":"/metadata/updated_at","value":"2026-07-10T21:11:56.435Z"}],"before_hash":"9bce6bcfb67395bd6b176246e31905894b6cbf601338842a0ff52e4332aaee4d","after_hash":"65672e0a58fa3fd21f2042f5d86a4586f4a71e1a3291da11b8dec5712e9047a6"}
{"ts":"2026-07-10T21:11:58.703Z","author":"codex-wide-pm-sdk","op":"close","patch":[{"op":"remove","path":"/metadata/assignee"},{"op":"replace","path":"/metadata/updated_at","value":"2026-07-10T21:11:58.703Z"},{"op":"replace","path":"/metadata/status","value":"closed"},{"op":"add","path":"/metadata/closed_at","value":"2026-07-10T21:11:58.702Z"},{"op":"add","path":"/metadata/close_reason","value":"Addressed Greptile and CodeRabbit claim-next contract, author, XOR, and completion findings with full coverage."}],"before_hash":"65672e0a58fa3fd21f2042f5d86a4586f4a71e1a3291da11b8dec5712e9047a6","after_hash":"93399e4cdc10239426138cf953504944cdd953ecd8a438c74b5a4c00a7aa5ff3"}
{"ts":"2026-07-10T21:11:59.596Z","author":"codex-wide-pm-sdk","op":"release","patch":[{"op":"replace","path":"/metadata/updated_at","value":"2026-07-10T21:11:59.596Z"}],"before_hash":"93399e4cdc10239426138cf953504944cdd953ecd8a438c74b5a4c00a7aa5ff3","after_hash":"e9cc9f591fa88f8543a71e3c5c2872c050b00e0f09917d45e47c03cf4acc7dbe"}
Loading
Loading