feat(cli): claim and start contributor tasks with explicit retry keys

[Abiorh001]

Change

WS-CLI-001-06 — Public contributor task claim/start.

Goal and intent

Extend contributor discovery with purposeful claim/start commands, not a second
authorization or task lifecycle implementation.
Bounded record.

What changed and design

• task claim TASK_ID --idempotency-key UUID [--reason TEXT] and task start.
• One fixed public POST, unchanged caller bearer and explicit key; no preflight,
  automatic key/retry, operator override or local authority.
• Strict contributor projection and composite assignment/task/project/policy
  identity, complete escaped text and preserved successful API JSON.
• Strict canonical API 4xx establishes known denial; other write failures are
  uncertain. Observation is not rollback proof; manual replay preserves the
  unchanged action/task/reason/key and can be denied after authority/state changes.
• External repair disables mutation body rewinding so Go cannot silently replay
  sent task POST or existing profile PATCH bodies after HTTP/2 GOAWAY. Profile
  payload and error classification remain unchanged; its existing no-retry
  contract is restored by the same shared guard.

Scope control and product behavior

CLI source/tests and affected README, roadmap and Commitrail only. Current main
is incorporated; both CLI06 and main's ARCH-04E1B-B2 initiative updates are retained.
Backend, MCP, workflows and dependency files are unchanged. Workstream still
owns authority, transactions, audit and replay. No submission/review activation,
binary publication or deployed-provider claim.

Evidence

Candidate: 597bde00544107ee93b1c43e1a5c46bf8cb45887.

• Go verify/tidy-diff/vet, clean CGO-disabled build, Ruff and format passed.
• Commitrail, six Markdown link checks, four stale scans and 16 workflow guards passed.
• Current-head targeted task/PATCH HTTP2 and uncertainty tests: 3 passed in 3.72s.
• Current-head complete HTTP process suite: 31 passed in 60.32s.
• Current hosted CLI/public API job:
  all 32 tests passed in 41.70s on PostgreSQL16 through migration0020, with cleanup.
  Checkout 3535561e and head 597bde00 share exact tree
  28d145d26052f4e3c5c24a1702dc271df6f0b786.
• Current full Backend run
  passed all nine lanes and the required aggregate: 8,652 unique case completions,
  zero skips/deselections, plus the real public-API end-to-end drill. Every lane
  exited0 without interruption; no retry was needed on this head. Agent Gates
  and both MCP checks also passed.
• The prior 6c885424 local PostgreSQL16 attempt reached the unchanged 240-second deadline
  (exit124); exact-head/migration0020 and complete database cleanup are recorded.
  This timeout is not a pass.
• Hosted CLI/public API job
  passed all 31 tests on previous head 6c885424 in 48.64s with real PostgreSQL16/migration0020, zero skips
  or deselections and complete isolation cleanup/container teardown. Checkout
  9c32f096 and that prior head share exact tree 6c0f591ba08b3274e4cc1d424cabd2471b776cd0.
  This is historical proof, not a current-head pass.
• Previous head's 30 CLI and 8,636 Backend tests passed; those are historical,
  not passing evidence for this repaired push. Required hosted checks must rerun.

Test delta and external findings

Existing tests remain selected; no tests removed, skipped or weakened.
The public API journey proves persisted claim/start, fresh authority, assignment
lineage, exact replay, conflicts and absent/foreign/Reviewer/revoked/suspended
denials. HTTP cases protect wire/input/output, composite identity and uncertainty.

• EXT-CLI06-HTTP2-REPLAY (P2): repaired by disabling task POST GetBody.
  A real TLS/ALPN HTTP2 peer receives the complete body before graceful GOAWAY.
  The new process regression fails on the previous binary (two connections),
  passes on the repair (one request and unknown outcome), and covers claim/start.
• EXT-CLI06-NULL-DETAILS (P3): added an otherwise complete HTTP403 envelope
  with null details. Removing only the existing non-null guard makes the test
  fail at its intended unknown-outcome assertion; the baseline passes.
• EXT-CLI06-PATCH-REPLAY: tracing the same owner reproduced two complete
  profile PATCH bodies after GOAWAY on 6c885424. The shared one-shot mutation
  guard and dedicated profile process regression restore its existing contract.

Impact-routed reviews and external checks

Affected security, architecture/documentation and QA/test-delta reviews pass on
the clean final candidate. No open internal findings remain.
CodeRabbit reported no actionable comments on 6c885424; its check on this final
push is rate-limited, not a fresh substantive review. No GitHub review threads exist.
The prior Backend run hit its unchanged 1,200-second task-lane execution deadline:
528 case completions were recorded, but no pytest final summary. It is not a pass
or current-head evidence. The fresh current-head run passed in full.

CI integrity, remaining risks and human focus

No workflow/dependency/gate changes, percentage quotas, test weakening or timeout
increase. Assignment invalidation is asynchronous. Local Flow/inference/storage
fixtures do not certify deployed providers. Review explicit retry-key handling,
composite contributor projection and uncertain outcomes. Further public journeys
and binary distribution remain later work.

Human approval/merge remains required; this PR does not authorize either.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: 682033da-4c39-4d80-8298-97d90350904a

📥 Commits

Reviewing files that changed from the base of the PR and between c7f91ac and 6c88542.

📒 Files selected for processing (17)

• .commitrail/INDEX.md
• .commitrail/initiatives/WS-CLI-001/OVERVIEW.md
• .commitrail/initiatives/WS-CLI-001/WS-CLI-001-06.md
• README.md
• cli/README.md
• cli/internal/api/client.go
• cli/internal/api/task_mutations.go
• cli/internal/command/command.go
• cli/internal/command/contributor_tasks.go
• cli/internal/command/task_mutations.go
• cli/tests/integration/conftest.py
• cli/tests/integration/contributor_task_journey.py
• cli/tests/integration/http2_fixture.py
• cli/tests/integration/test_contributor_task_mutations.py
• cli/tests/integration/test_http_boundary.py
• cli/tests/integration/test_public_self_service.py
• docs/roadmap_status.md

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The CLI adds contributor task claim and start commands through public REST operations. The commands require caller-supplied idempotency keys, validate responses, and report uncertain outcomes without automatically retrying.

Changes

Contributor task writes

Layer / File(s)	Summary
Write contract and API behavior .commitrail/initiatives/WS-CLI-001/WS-CLI-001-06.md, cli/internal/api/task_mutations.go, cli/internal/api/client.go	The API client adds keyed claim and start requests, validates inputs and responses, and classifies incomplete or noncanonical mutation outcomes as unknown.
CLI command and output flow README.md, cli/README.md, cli/internal/command/*	The CLI registers task claim and task start. Both commands support JSON and human-readable output, and their documentation describes the request and retry behavior.
Mutation verification and delivery record .commitrail/INDEX.md, .commitrail/initiatives/WS-CLI-001/*, cli/tests/integration/*, docs/roadmap_status.md	Integration tests cover request and response handling, authorization, replay, and no-retry behavior. The initiative and roadmap records include claim and start in the delivered boundary.

Priority: ➖ Normal

Estimated code review effort: 4 (Complex) | ~45 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant TaskCommand
  participant APIClient
  participant PublicRESTAPI
  TaskCommand->>APIClient: ClaimTask or StartTask with task ID, key, and reason
  APIClient->>PublicRESTAPI: POST mutation with Idempotency-Key
  PublicRESTAPI-->>APIClient: Mutation response or API error
  APIClient-->>TaskCommand: Validated result or failure

Loading

Merge Risk: ⚪ Minimal · up to 6c885

No actionable claim/start risk remains identified; the PR is mergeable after normal checks.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 8.82% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 34 functions across 11 files. (6 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
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.
Title check	✅ Passed	The title clearly and concisely describes the main change: adding contributor task claim and start commands with explicit retry keys.
Description check	✅ Passed	The description covers the change, intent, design, scope, product behavior, evidence, test changes, external findings, CI integrity, risks, and human review. It omits some template structure and detai…

Full details: Docstring Coverage

Explanation

Docstring coverage is 8.82% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 34 functions across 11 files. (6 skipped: 6 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

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.}