feat(cli): browse contributor ready tasks and instructions

[Abiorh001]

Change

WS-CLI-001-05 — contributor ready-task discovery and detail.

Goal

Let contributors browse ready work and inspect instructions without manager
metadata, task writes, or client-owned authorization.

Intent And Planning Context

Bounded change record
owns the design, acceptance criteria, alternatives and remaining boundary.

What Changed

• workstream task ready PROJECT_ID [--limit N] [--cursor CURSOR] calls the
  existing public contributor queue once.
• workstream task show TASK_ID calls the existing public contributor detail once.
• Preserve exact JSON, complete escaped text, UUID identity and nullable fields;
  reject malformed, substituted or management-only response data before output.
• Reuse existing safe transport, pagination and decoding helpers. Reconcile CLI
  docs, root README, roadmap, overview and index in the same change.

Scope Control

Only CLI code/integration tests and affected documentation/Commitrail records
changed. No backend, MCP, dependency, workflow or CI configuration changes.

Product Behavior

• No Workstream product behavior changed. The CLI exposes existing public reads;
  AUTH/TASK retain grant, lifecycle, state and assignment decisions.

Evidence

Go module verification/tidy, vet/build, Ruff/format, links, four stale scans,
Commitrail and all 16 workflow-integrity tests passed on the reviewed head.

Current candidate: 55704f73, reconciled with main 31ac857b. Both CLI-05 and
ARCH-04E1B-B1 index entries are retained, along with main's roadmap updates.
The mixed canonical/compact duplicate UUID regression passes. Replacing only
normalized duplicate tracking with raw-string tracking fails its exact assertion
(erroneous success instead of invalid_api_response). Existing duplicate and
independent page-size controls remain.

All 24 local HTTP process tests passed in 60.45s. Local combined and separate
real-API attempts hit the unchanged 240-second deadline; both cleaned their
isolated PostgreSQL database at Alembic 0020_review_admission_lock_order and
are not counted as passes.
Fresh hosted CLI Public Contract
passed the complete 25-test process/real-API suite in 43.65s (job 1m53s), using
the unchanged 240-second deadline and migration 0020. Tested merge commit
5ef2308b and review head 55704f73 have the identical Git tree
2347ce43b83427a7122dbcab5a0ec753383fdf09.
Full Backend
passed: 8,636 canonical tests completed across nine accepted lane bundles, zero
skips/deselections and no duplicate completed identities. All nine exact-source
PostgreSQL/MinIO cleanup records are complete at migration 0020. Agent Gates
and both MCP jobs passed too.

Attempt 1 reached the unchanged 1,200-second task-lane deadline after 516/527
tests completed, with no assertion failure shown and cleanup confirmed. The
unchanged-source retry completed all 527 task-lane tests within that deadline
(lane execution 1,161.755s). The final aggregate retained the eight passing
attempt-1 bundles and selected the successful task-lane attempt-2 bundle;
the original partial failure remains recorded and was not combined as success.
No source, selection, timeout or workflow changes were made to obtain the pass.

Acceptance Criteria Proof

• Exact fixed public reads, unchanged bearer, one request per command and no
  preflight/retry/automatic pages.
• Separate contributor shapes, full text/JSON preservation, encoded selectors,
  null/omission, malformed replies, response bounds and redirect refusal.
• Real persisted ready tasks in two active projects; three-page parity,
  draft/claimed exclusion, own-assignment detail and same-project non-owner denial.
• Exact Submitter success; absent, Reviewer-only, foreign, revoked and suspended
  denial; independently authorized action/project/limit cursor substitution.

Test Delta

Three grouped HTTP process tests added. The existing real API journey is extended
through one cohesive helper, reusing its bootstrap and server. No tests/assertions
removed, skipped or weakened; no test-count or coverage target.

Upstream approved-guide prerequisites reuse canonical fixtures. Inference/storage
are scripted prerequisites, not live Flow, guide-provider or S3 certification.
Real AUTH activates those projects; task/grant/lifecycle operations use public HTTP.

Impact-Routed Reviewer Results

Current review target: 55704f7338031f5880e8c153628b5216db27a878.
Base/merge-base: 31ac857ba5611019ac6ef2418753d3625e952497.
All three affected assignments replayed this target with matching clean
start/end snapshots. No findings remain. Earlier reviews are historical.

Tracks / reviewer session	Result	Independent probe
Security (cli_security)	PASS	Public read owners/credential boundaries retained; mixed-spelling mutant fails.
Architecture + documentation (cli_arch_docs)	PASS / PASS	Production-owner drift and conflict-loss probes detect lost main/CLI boundaries.
QA + test delta (cli_qa)	PASS / PASS	Mixed-spelling duplicate regression and independent raw-string mutant failure.

These are advisory mirrors, not receipt custody. Proof spans built-process
service/composition behavior and real stored PostgreSQL project/assignment
isolation. Scripted upstream guide inputs and local tokens remain fixture
boundaries; deployed providers and hosted checks are not inferred from them.

External Review

CodeRabbit completed a fresh substantive incremental review at 55704f73, with
six files processed and no actionable comments (run
918ae74d-c1b0-4989-a46c-68d0e2907e52). No review threads exist. Its default
docstring quota is not a repository gate or a behavior defect. The supplied
review's conflict and P3 normalization-proof gap are repaired in this candidate.
Human approval and merge remain required; none is inferred.

CI And Gate Integrity

• No workflow, lint/test/doc or package-script weakening.
• Tests protect behavior and failure boundaries; coverage remains diagnostic.
• No new dependencies/actions, skip/deselection or timeout increase.

Remaining Risks

Ready-work discovery is not a reservation or claimability guarantee. A later claim
must reauthorize. The existing 64 KiB response bound may require a smaller page.
These source commands do not imply binary distribution, deployment or completed
submission/acceptance integration.
The existing full-backend timing bottleneck remains; this bounded CLI change
does not repair lane capacity or introduce selective testing.

Human Review Focus

Contributor-only fields, exact-resource binding, one-page continuation and
server-owned current authority/assignment visibility.

Human Merge Ownership

• I can explain what changed and why.
• I know what could break and accept the remaining risks.
• The user explicitly approved this specific PR for merge.

[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: 918ae74d-c1b0-4989-a46c-68d0e2907e52

📥 Commits

Reviewing files that changed from the base of the PR and between bd0cf34 and 55704f7.

📒 Files selected for processing (6)

• .commitrail/INDEX.md
• .commitrail/initiatives/WS-CLI-001/WS-CLI-001-05.md
• README.md
• cli/tests/integration/test_contributor_task_http.py
• cli/tests/integration/test_public_self_service.py
• docs/roadmap_status.md

🚧 Files skipped from review as they are similar to previous changes (2)

• .commitrail/INDEX.md
• 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 Go CLI adds contributor commands to list ready tasks and read task instructions. The commands use existing public REST routes, apply response validation, and include integration coverage for output, pagination, authority, and assignment visibility.

Changes

Contributor task reads

Layer / File(s)	Summary
API reads and response validation cli/internal/api/contributor_tasks.go, cli/internal/api/tasks.go, .commitrail/initiatives/WS-CLI-001/WS-CLI-001-05.md	Adds API response types and client methods for ready-task pages and task details. Shared task-page query and response validation are extracted, and task field decoding now validates required strings.
CLI commands and usage cli/internal/command/*, cli/README.md, README.md, .commitrail/INDEX.md, .commitrail/initiatives/WS-CLI-001/OVERVIEW.md, docs/roadmap_status.md	Registers task ready and task show. Documents their output, routes, authority, pagination, and limits; updates initiative and roadmap status.
Integration verification and completion records cli/tests/integration/*contributor*, cli/tests/integration/test_public_self_service.py, .commitrail/initiatives/WS-CLI-001/WS-CLI-001-05.md	Adds HTTP and public API integration coverage for command output, response validation, pagination, authority, assignment visibility, and actor status. Records acceptance criteria and verification evidence.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant Contributor
  participant CLI
  participant APIClient
  participant PublicRESTAPI
  Contributor->>CLI: Run task ready or task show
  CLI->>APIClient: Request contributor task read
  APIClient->>PublicRESTAPI: Send fixed-route GET request
  PublicRESTAPI-->>APIClient: Return task data
  APIClient-->>CLI: Return validated response
  CLI-->>Contributor: Print text or JSON output

Loading

Merge Risk: ⚪ Minimal · up to 55704

The contributor task-read commands appear ready to merge after normal checks.

Security Architecture Review

Security architecture risk: 🔵 Low · up to 55704

The new commands provide narrowly scoped reads while leaving access decisions on the server. The examined paths preserve credential protections and reject invalid or management-only responses before output. No authorization bypass was identified, but deployment-wide security coverage remains incomplete.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — The added interface increases CLI accessibility to contributor task information, not server-granted authority. A ready request targets one project and at most 100 items; a detail request targets one task. Effective disclosure remains subject to the existing authenticated server routes rather than client-owned grants.

Trust Boundaries and Controls

• observed — User-controlled selectors cannot replace the configured API origin: validated selectors are path-escaped and cursor values are query-encoded. Existing transport validation permits HTTPS or loopback HTTP origins, disables proxy inheritance and refuses redirects, constraining bearer-token forwarding.
• observed — Task content crosses a response-to-output boundary only after closed-schema and identity validation. Text rendering escapes nonprinting and Unicode format characters; JSON output retains the validated response rather than adding management fields.

Resilience and Maintainability Implications

• observed — The contributor reads inherit bounded transport failures and safe error metadata. HTTP failures, invalid content types, oversized bodies and malformed responses return errors before successful task output; this preserves failure containment without introducing task-write recovery states.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 5.88% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 17 functions across 7 files. (4 skipped: 4…	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 CLI support to browse contributor-ready tasks and instructions.
Description check	✅ Passed	The description is detailed and covers the goal, scope, behavior, evidence, acceptance criteria, test changes, reviewer results, risks, and human review. It links to the design record for planning det…

Full details: Docstring Coverage

Explanation

Docstring coverage is 5.88% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 17 functions across 7 files. (4 skipped: 4 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.}

[Abiorh001]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[Abiorh001]

CodeRabbit completed a fresh review of bd0cf34 with no actionable findings. The default docstring-percentage warning is advisory, not a repository gate; this slice retains behavior-focused process/API proof rather than quota-driven comments or unit tests.