feat(cli): inspect Finance contribution-policy versions

[Abiorh001]

Workstream PR Trust Bundle

Current repair target: 87e5219fd4d58917f8311ff7528bda4657f24840, base 6d64a6353fd619f5b917359da8b82c307d97d40d. Latest main is incorporated without conflicts. The previous 6ed2c521 run failed before tests because public ECR refused the Redis image with Data limit exceeded; main's same-digest Docker Hub correction is now included. New hosted run 38355145838 is pending. Earlier SHA-bound results below are historical, not current-head passing evidence. Affected reviews are being replayed; do not merge until current CI and review are complete.

Change

WS-CLI-001-22 — Finance contribution-policy inspection

Goal

Give current Finance Authorities public CLI discovery and exact-version inspection before adding policy writes.

Intent And Planning Context

• Bounded record
• Initiative

What Changed / Design Chosen

• project contribution-policy current PROJECT_ID: one public GET for the aggregate and nullable published/open-draft selectors.
• project contribution-policy show PROJECT_ID POLICY_ID [--version UUID]: one public GET for backend-selected or explicit retained history. Published selection takes precedence over an open successor draft by backend policy.
• Complete escaped text/raw JSON, UUID identity binding, required closed nested facts, independent status enums, positive arbitrary-range version integers and exact decimal-string quantities.
• Reuses existing JSON transport, decoded credential protection, UUID helpers and scalar award validation; no copied economics/readiness/authorization rules.
• Extends the retained public activation journey instead of adding another backend daemon fixture; updates README/CLI docs, affected roadmap trace and overview/index together.

Scope Control / Alternatives Rejected

Only CLI code/tests and affected docs/Commitrail changed. No backend, migrations, dependencies, workflow or budget changes. No Finance grants, policy writes, current-selector preflight, cache, retry loop or local eligibility subsystem. Source availability is not deployment or binary distribution.

Product Behavior

• No Workstream backend product behavior changed. The CLI consumes two already-public Finance reads; PM-only authority does not suffice.

Evidence

Clean candidate: 369d91c194014205d6882bb926c0a26b035db021; base/merge-base: 51c7e2eed53b4fd45b3ae201ef3b30445c233a09.

go -C cli build -trimpath -o /tmp/workstream-cli22-candidate ./cmd/workstream
go -C cli vet ./...
go -C cli mod verify
go -C cli mod tidy -diff
WORKSTREAM_CLI_EXECUTABLE=/tmp/workstream-cli22-candidate backend/.venv/bin/python -m pytest -q cli/tests/integration/test_contribution_policy_reads.py cli/tests/integration/test_contributor_task_http.py
# From backend/, isolated real PostgreSQL with the built executable:
.venv/bin/python scripts/run_isolated_tests.py --metadata-json /tmp/workstream-cli22-candidate-isolation.json --timeout-seconds 600 -- .venv/bin/python -m pytest -q ../cli/tests/integration/test_guide_activation_public_api.py

Build/vet/module verification/tidy-diff, Ruff, links, four stale scans, Commitrail and diff checks passed. Built binary records exact candidate with vcs.modified=false. Seven focused process tests passed (four new, three retained).

The clean candidate native public-socket/Flow/PREP/PostgreSQL journey passed (1 test, 164.53s). Isolation metadata binds 369d91c194014205d6882bb926c0a26b035db021, schema 0035_checker_retry, and database/role cleanup; the direct cleanup query found no retained test database or role. No MinIO claim is made by this journey. The earlier dirty exploratory run is excluded from exact-head evidence.

Hosted Backend run 38282008787 passed, including all ten lanes, the aggregate public API drill and CLI job 114921274330 (157 tests in 210.75s). Its tested merge 451a37b078092627209ce0a66ce638aa5d7a1727 has parents exactly the base/head above and the identical Git tree 40ad260e3aea9fc37d9c7fff943b230b5bd63aad. This is merge execution with verified source compatibility, not a relabeled direct-head run.

Exported artifact 11762323183 independently confirms 9,204 collected/completed/unique backend cases, identical membership, zero skips/deselections, and all ten PostgreSQL/MinIO source-bound cleanup/probe records. Backend wall time was 1,342.769s and the timing target was not met; this PR makes no whole-CI performance claim. Agent Gates and both MCP checks passed too.

Acceptance Criteria Proof / Test Delta

• Process tests: nullable selectors, empty/unpaid/compensated graphs, backend-sized integers, full text/JSON, exact quantities, alternate UUID spellings, explicit version binding, malformed/unknown/null/duplicate nested facts, normalized duplicate IDs, size bounds, canonical denial and credential reflection.
• Real API journey: empty draft, publication, simultaneous published/open-draft selectors, default/explicit version selection, retained retirement, stored foreign policy/version, PM-only and foreign Finance denial, public suspend/reactivate and revoke/restore; full CON/guide SQL snapshots preserve business state. AUTH read evidence is intentionally excluded.
• Original activation/replay/retirement assertions retained. No tests removed, skipped or weakened. Shared scalar refactor retains contributor proof.
• Independent test-of-test: removing returned project binding passes the positive control and fails the named foreign-project response regression. Unchanged-source explicit version-substitution and independent historical-status probes also passed.

Impact-Routed Reviewer Results

Reviewed code SHA: 369d91c194014205d6882bb926c0a26b035db021.

Reviewer	Result	Blocking findings	Proof boundary and uncertainty
Security — /root/cli10_security	PASS	None	Exact target/credential/public Finance boundary and real stored-resource/withdrawn-authority custody verified
QA/test delta — /root/cli10_qa	PASS	None	Exact process/native evidence, retained behavior and discriminating mutation verified
Architecture/docs/reuse — /root/cli10_plan	PASS	None	Owner boundaries, shared validation and affected ledger checked; explicit-version/status probes passed

These are non-authoritative mirrors of local session evidence; GitHub remains repository authority.

External Review

CodeRabbit: not fresh — review rate-limited (next included review reported in 50 minutes); its green check is not substantive review. No review threads were present at final inspection. All reported hosted checks passed. GitHub reports the PR mergeable and requires eligible human approval; no merge was performed.

CI And Gate Integrity

• No workflow, package script, checkout or dependency change.
• No test selection, timeout or complete-execution weakening.
• Tests protect behaviors/failure boundaries; coverage is diagnostic, not a threshold.

Remaining Risks / Follow-Up Work

Compensated precision is process-boundary proof, not new native compensated-policy or payout certification. Existing backend economics integration remains in full hosted CI. Finance editing/publication/retirement, contribution evidence, later public submission/review/revision, published binaries and optional TUI remain outside this PR. Hidden APIs and other agents' bulk work are not exposed or taken over.

Human Review Focus

Confirm Finance-only current authorization; published/default versus explicit draft/history selection; complete exact quantities; reads never edit, publish, activate or grant authority.

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.

Summary by CodeRabbit

• New Features
  • Added CLI commands to discover a project’s current contribution-policy selectors and inspect a policy version, including a specific retained version.
  • Policy reads require current Finance Authority and do not change policies or authorize payments.
• Documentation
  • Updated CLI guidance and roadmap information to explain policy discovery, version selection, access requirements, and the limits of these read-only commands.

[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: 43d63486-3b47-4013-a449-eb194f27ffc1

📥 Commits

Reviewing files that changed from the base of the PR and between 6ed2c52 and 87e5219.

📒 Files selected for processing (3)

• README.md
• cli/tests/integration/test_guide_activation_public_api.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

The CLI adds current and show commands for contribution-policy reads. The API client validates returned selectors and policy versions. Integration tests and documentation cover version selection, Finance authority, response handling, and read-only behavior.

Changes: Contribution Policy Reads

Layer / File(s)	Summary
API read models and validation cli/internal/api/contribution_policy_reads.go, cli/internal/api/contributor_tasks.go	Adds API response models and client methods for current selectors and policy versions. The client validates response identities, statuses, rules, definitions, and award data.
CLI command exposure cli/internal/command/contribution_policy_reads.go, cli/internal/command/command.go	Registers project contribution-policy current and show. The commands pass optional version selection to the API client and write JSON or task-context output.
Read behavior verification cli/tests/integration/*contribution_policy*, cli/tests/integration/test_guide_activation_public_api.py	Adds coverage for policy lifecycle reads, Finance authorization changes, malformed responses, output handling, and read-only behavior. The activation integration test now exercises retired-version inspection.
Capability scope and documentation .commitrail/INDEX.md, .commitrail/initiatives/WS-CLI-001/*, README.md, cli/README.md, docs/roadmap_status.md	Documents current and version-specific reads, Finance authority, backend version selection, and the separation between reads and policy writes.

Priority: ⬇️ Low

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

Change: Feature

Merge Risk: ⚪ Minimal · up to 87e52

The documentation updates and guide integration-test changes show no remaining merge-blocking risk.

Pre-merge checks · 4 · 1

Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 5.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 20 functions across 7 files. (2 skipped: 2…	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.
Title check		The title clearly identifies the main change: adding CLI inspection for Finance contribution-policy versions.
Description check		The description is substantially complete. It documents the goal, scope, design, evidence, acceptance criteria, reviewer status, risks, follow-up work, and human review focus. Some template headings a…

Full details: Docstring Coverage

Explanation

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

• Autofix · 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.}