feat(cli): inspect Finance contribution-policy versions

.commitrail/INDEX.md

@@ -8,7 +8,7 @@ for current product capability.
 |---|---|---|
 | [WS-DB-002](initiatives/WS-DB-002/OVERVIEW.md) | Complete | Shared UUIDv7 record generation, native-UUID relationships and fresh v0.1 baseline; natural-owner retry custody and aligned CI/local setup |
 | [WS-MCP-002](initiatives/WS-MCP-002/OVERVIEW.md) | Planned | Nine tools through WS-MCP-002-03: self-service and administrative reads; 18 tools remain and WS-MCP-002-04 administrative grant mutations are next |
-| [WS-CLI-001](initiatives/WS-CLI-001/OVERVIEW.md) | Planned | Public Go CLI self-service, inspection, task browsing/claim/start, governing context, project creation/declaration, original upload, setup diagnostics, exact proposal inspection, intake/evaluation approval, guide/evaluation correction, explicit saved-successor dispatch, exact guide activation, separate manager task creation/screening/release, explicit Submitter/Reviewer issuance/revocation and filtered grant/qualification history delivered through WS-CLI-001-21; PILOT-13 assigned-guide listing/download is delivered; further public journeys and binary distribution remain; hidden submission is not exposed |
+| [WS-CLI-001](initiatives/WS-CLI-001/OVERVIEW.md) | Planned | Public Go CLI self-service, inspection, task browsing/claim/start, governing context, project creation/declaration, original upload, setup diagnostics, exact proposal inspection, intake/evaluation approval, guide/evaluation correction, explicit saved-successor dispatch, exact guide activation, separate manager task creation/screening/release, explicit Submitter/Reviewer issuance/revocation, filtered grant/qualification history and Finance policy discovery/version inspection delivered through WS-CLI-001-22; PILOT-13 assigned-guide listing/download is delivered; Finance policy writes, contribution evidence, further public journeys and binary distribution remain; hidden submission is not exposed |
 | [WS-ARCH-001](initiatives/WS-ARCH-001/OVERVIEW.md) | Planned | Hidden authorized outcomes now bind exact phase/routing receipts and replay. B8 supplies completion delivery; 04F1 supplies verified failure evidence; 04F2 supplies the exact current checker-remediation TASK/AUTH handoff under both policy modes without REV/CON; 04F3 supplies hidden exact-cause replacement through canonical intake and writer; 04F4 supplies hidden reason-bound Operator retry with exact receipt, audit and request-event custody. Manager-visible setup-fault hold is next, followed by live composition, public intake and the [first-layer drill](initiatives/WS-ARCH-001/planning/PLAN.md#first-complete-contributor-milestone). False-guide activation remains unavailable. |
 | [WS-ART-001](initiatives/WS-ART-001/OVERVIEW.md) | Planned | Exact checker input/output custody, packet foundations and the 04F2 hidden remediation handoff through existing TASK/AUTH owners are delivered. 04F3 hidden exact-cause replacement through existing ART ports and 04F4 hidden Operator retry are delivered; manager-visible setup-fault hold, production composition/readiness, public intake and the drill remain. |
 | [WS-AUTH-001](initiatives/WS-AUTH-001/OVERVIEW.md) | Planned | ARCH-04E2-B supplies canonical fixed-router custody for hidden success outcomes; B8 supplies completion delivery and 04F2 supplies the exact policy-independent remediation consequence with no REV/CON effect. 04F3 hidden exact-cause replacement and 04F4 hidden Operator retry are delivered; manager-visible setup-fault hold, production registration/readiness, public intake and the drill remain; live human acceptance authority stays deferred. |

.commitrail/initiatives/WS-CLI-001/OVERVIEW.md

@@ -26,6 +26,7 @@
   [WS-CLI-001-19](WS-CLI-001-19.md), separate manager draft creation, screening and release;
   [WS-CLI-001-20](WS-CLI-001-20.md), explicit exact-project Submitter/Reviewer issuance and revocation;
   [WS-CLI-001-21](WS-CLI-001-21.md), filtered grant browsing and exact qualification/revocation history;
+  [WS-CLI-001-22](WS-CLI-001-22.md), Finance current policy discovery and exact retained-version inspection;
   [PILOT-13](../../changes/pilot13-assigned-task-guide-documents.md), assigned-task locked-guide listing/download.
 
 ## Current boundary
@@ -111,6 +112,12 @@ owned; no role cache, automatic grant or AdminRole command is added.
 explicit opaque continuation; `project role-grant show PROJECT_ID GRANT_ID`
 observes exact public qualification, provenance and revocation history. Neither
 read grants authority or verifies permission for a later write.
+`project contribution-policy current PROJECT_ID` and
+`project contribution-policy show PROJECT_ID POLICY_ID [--version UUID]` expose
+the complete authorized Finance policy graph and current selectors. The backend
+selects the published version ahead of an open draft unless explicitly overridden
+by a version selector; current Finance authority governs historical reads too.
+PM-only authority does not suffice. These reads never publish, retire or pay.
 All have text/JSON
 output and built-binary integration proof. Mutations preserve omitted/null
 semantics and explicitly report uncertain outcomes without automatic retries.
@@ -203,11 +210,15 @@ CLIs. Keep the package independent of backend and MCP runtime dependencies.
 21. **WS-CLI-001-21:** Filtered project-grant pagination and exact grant history
    through public GETs, complete qualification/provenance disclosure and fresh
    authority on each call. No actor discovery or automatic decisions.
-22. **Later governed-work commands:** Add further project setup, submission,
+22. **WS-CLI-001-22:** Current Finance policy discovery and backend-selected or
+   exact retained-version inspection, including empty drafts and complete award
+   definitions. No Finance mutation, publication or local readiness decisions.
+23. **Later governed-work commands:** Add explicit Finance policy editing,
+   publication/retirement and contribution-evidence reads, then submission,
    review, revision, and contribution reads/writes only as their actual public
    contracts and authority boundaries become available. Split by user journey,
    not one PR per endpoint or one giant catalogue PR.
-23. **Optional TUI:** Add a focused public queue/evidence view after its API
+24. **Optional TUI:** Add a focused public queue/evidence view after its API
    workflow is complete. Never require a TUI for agents or scripts.
 
 ## Risks and proof

.commitrail/initiatives/WS-CLI-001/WS-CLI-001-22.md

@@ -0,0 +1,119 @@
+# WS-CLI-001-22 — Inspect contribution-policy selectors and versions
+
+- Initiative: `WS-CLI-001`
+- Durable disposition: `Complete`
+- Intended merge outcome: Finance Authorities discover current policy selectors and inspect exact retained policy versions through public REST reads.
+
+## Intent
+
+Complete policy inspection before adding Finance editing/publication commands.
+`project contribution-policy current PROJECT_ID` recovers the current aggregate,
+published version and open draft. `project contribution-policy show PROJECT_ID
+POLICY_ID [--version UUID]` inspects the owner's selected version or one explicit
+historical version. Observations do not grant write authority or prove readiness.
+
+## Current behavior
+
+CLI01–21 cover 32 documented public command surfaces through merged #545.
+`backend/app/api/routes/contribution_policies.py` already exposes public GET
+`.../contribution-policies/current` and `.../contribution-policies/{policy_id}`,
+with optional `version_id`. The CON service/repository own default selection and
+exact project/policy/version scoping; current discovery excludes retired
+aggregates. Exact retired versions remain readable with current Finance
+Authority. Project Manager authority alone does not authorize these operations.
+Guide activation is a separate manager action binding an exact published version.
+
+## Bounded change
+
+Allowed: new `cli/internal/api/contribution_policy_reads.go` and
+`cli/internal/command/contribution_policy_reads.go`; registration in command.go;
+extract the existing scalar award validation in contributor_tasks.go so ready
+work and policy reads reuse it without changing existing semantics; new
+`test_contribution_policy_reads.py` and `contribution_policy_read_journey.py`;
+small hook/fixture updates in the retained `test_guide_activation_public_api.py`;
+README, CLI README, affected roadmap sections, overview/index and this record.
+
+Prohibited: backend owners, policy/schema/migration/economic rules, adapter
+bindings, dependencies, CI configuration/budgets/selection, Finance granting
+commands, draft editing/publication/retirement CLI writes, hidden submission,
+bulk task work, automatic selection/retries or a generic administration layer.
+No copied currency catalogue, rounding or local payment eligibility decisions.
+
+## Design and decisions
+
+Use existing closed/null-aware JSON parsing, UUID identity, finite JSON transport,
+decoded credential protection and complete escaped text/raw JSON output. Preserve
+the original path/query UUID spelling. Current selector response has four fields;
+both version selectors are nullable, but a successful selection cannot have
+both null or the same normalized UUID in both roles. Version response retains
+complete rules and
+definitions, including Finance binding identifiers and exact string quantities,
+without treating an incomplete draft or historical version as ready. Reuse scalar
+award wire validation; do not copy backend publication/compensation business rules.
+Default show is explicitly backend-selected; an explicit --version must bind the
+returned version. No preflight, auto-current fetch or cached selectors.
+
+## Acceptance criteria
+
+- One public current or show GET; optional `version_id` is forwarded only when
+  requested. Invalid selectors/empty explicit version fail without HTTP.
+- Complete text/JSON projection for empty draft, unpaid rules, compensated
+  definitions and both nullable current selectors. Quantities retain exact text;
+  floats, null members, duplicate/unknown/missing fields and malformed identities
+  do not become successful facts. Unique normalized rule/definition identities,
+  exact requested project/policy/version hold. Close `contribution_type` to
+  `accepted_submission|completed_review`, `compensation_mode` to
+  `unpaid|compensated`, and `instrument_type` to `money|project_points`, with
+  otherwise-valid unknown-token regression cases.
+  Policy status is `draft|active|retired`; version status is
+  `draft|published|retired`. Preserve independently valid historical combinations,
+  not a local readiness matrix. `version_number` is a present positive integer
+  using the existing `big.Int` JSON pattern, without machine-integer narrowing.
+- Otherwise-valid current responses with both nullable selectors null, or the
+  same UUID under alternate spellings in both selectors, fail. Both one-null
+  variants and distinct both-present selectors remain valid. Invalid/missing/null
+  status/version facts fail after positive controls; oversized positive integers
+  retain exact JSON/text instead of overflowing the client.
+- Valid controls precede otherwise-valid foreign project/policy/version replies,
+  normalized duplicate IDs, malformed nested definitions and credential reflection.
+  Every invalid read leaves stdout empty; it is not an unknown write outcome.
+- Extend existing real public-socket/Flow/PREP/PostgreSQL guide activation proof,
+  not a second broad daemon fixture. Public setup exposes the existing unpaid
+  policy's empty draft, published graph, simultaneous published/open-draft
+  selectors and historical retirement. PM-only, other callers, a stored foreign
+  policy/version and a foreign-project Finance actor are denied. Suspend/reactivate
+  and revoke/restore Finance authority through existing public admin setup;
+  positive controls precede denials. Existing activation/replay/retirement checks
+  remain intact. Read snapshots cover all CON policy tables/lifecycle events,
+  excluding legitimate AUTH read evidence. Reads do not publish/edit/activate.
+- Compensated quantity precision is process-boundary proof, not a new native
+  compensated-policy or fulfillment certification. Existing backend economics
+  tests remain hosted; no payout or readiness claim is made by this client.
+- A target-binding or duplicate-normalization mutant must fail the specific
+  regression after its valid control. Full hosted execution remains blocking.
+
+## Risk and review routing
+
+- Risk class: `L1` — Finance-visible policy and binding facts, client reads only.
+- Plan review before code; security; QA/test delta; architecture/docs/reuse in
+  one bounded assignment. No CI changes and no ceremonial nine-agent fanout.
+- Human focus: Finance authority stays backend-owned; exact/default/historical
+  selection is explicit; no approval, payout or hidden capability is introduced.
+- No additional human design decision is needed.
+
+## Evidence
+
+Verification commands: independent Go build/vet/module verification/tidy-diff;
+`test_contribution_policy_reads.py` process suite plus retained contributor
+read proof for the scalar-validator refactor; isolated PostgreSQL execution of
+`test_guide_activation_public_api.py`; Ruff, links/stale scans, Commitrail/diff
+and complete hosted Backend/CLI collection. This disposition records the intended
+durable merge outcome, not transient CI/approval state. Exact execution and
+review freshness remain in the PR; source availability is not deployment.
+
+## Reconciliation
+
+- Main: #545 merged. PILOT-02 batch CLI and PILOT-04 intake are separate owners.
+- Next usable boundary: Explicit public Finance draft/update/publication commands;
+  contribution evidence reads; public submission/review/revision only when ready.
+- Remaining: Binary distribution and optional TUI; no exact chunk-count or delivery promise.

README.md

@@ -430,6 +430,11 @@ and fresh-authorized replay; receipts are observations, not cached permission.
 page; `project role-grant show PROJECT_ID GRANT_ID` inspects complete public
 qualification/provenance and revocation history. Pagination is explicit and
 fresh authority is backend-owned; a read never authorizes a later write.
+`project contribution-policy current PROJECT_ID` discovers the published and
+open-draft selectors; `project contribution-policy show PROJECT_ID POLICY_ID
+[--version UUID]` inspects backend-selected or exact historical policy versions,
+including complete rules and exact quantities. These require current Finance
+Authority, not PM-only permission; they do not edit, publish, retire or pay.
 All support human-readable and JSON output, using the caller's Flow token.
 The first source package is buildable; further workflow commands and published
 binaries remain planned.

cli/README.md

@@ -33,6 +33,8 @@ context/intake requirements:
 | `workstream project role-grant revoke PROJECT_ID GRANT_ID --input FILE --idempotency-key UUID` | `POST /api/v1/projects/PROJECT_ID/role-grants/GRANT_ID/revoke` |
 | `workstream project role-grant list PROJECT_ID [--status active\|revoked] [--role submitter\|reviewer]` | `GET /api/v1/projects/PROJECT_ID/role-grants` |
 | `workstream project role-grant show PROJECT_ID GRANT_ID` | `GET /api/v1/projects/PROJECT_ID/role-grants/GRANT_ID` |
+| `workstream project contribution-policy current PROJECT_ID` | `GET /api/v1/projects/PROJECT_ID/contribution-policies/current` |
+| `workstream project contribution-policy show PROJECT_ID POLICY_ID [--version UUID]` | `GET /api/v1/projects/PROJECT_ID/contribution-policies/POLICY_ID` with optional `version_id` |
 | `workstream task ready PROJECT_ID` | `GET /api/v1/projects/PROJECT_ID/tasks/ready` |
 | `workstream task show TASK_ID` | `GET /api/v1/tasks/TASK_ID` |
 | `workstream task claim TASK_ID --idempotency-key UUID` | `POST /api/v1/tasks/TASK_ID/claim` |
@@ -202,6 +204,43 @@ and credential reflection fail with empty stdout. These reads require the
 backend's covered Project Manager or Audit Authority, not a contributor grant.
 They do not cache permission, authorize a later write, or establish rollback.
 
+## Inspect contribution policies
+
+```sh
+workstream project contribution-policy current PROJECT_ID -o json
+workstream project contribution-policy show PROJECT_ID POLICY_ID -o json
+workstream project contribution-policy show PROJECT_ID POLICY_ID --version VERSION_ID -o json
+```
+
+These are Finance Authority reads, not Project Manager permissions. Workstream
+requires current covering Finance authority and active admission for each call;
+PM-only, foreign-project or withdrawn authority remains a concealed server denial.
+Each command sends one public GET, without a preflight or automatic selector fetch.
+
+`current` returns the aggregate ID and nullable published/open-draft version IDs.
+`show` without `--version` uses backend selection: the published version takes
+precedence over an open successor draft. Supply `--version` to inspect that draft
+or an exact retained historical version. Retired aggregates are excluded from
+current discovery but exact historical inspection remains authorized separately.
+An explicitly empty or invalid selector fails before HTTP; UUID spelling is
+preserved in the request and compared by identity in the response.
+
+Both output formats retain all authorized fields: policy/version identity and
+status, positive integer version number, complete rules and award definitions,
+including binding IDs and exact decimal-string quantities. Empty drafts are
+valid observations, not readiness. JSON preserves the API object; complete text
+escapes terminal controls. Missing, null, unknown, duplicate, substituted or
+credential-reflecting facts fail with empty stdout. These commands never publish,
+retire, pay, activate a guide or authorize a later write.
+
+Native proof extends the existing public guide-activation journey with empty
+drafts, unpaid publication, simultaneous published/draft selection, exact history,
+foreign stored policies/versions, and public Finance suspension/revocation with
+restored positive controls. Policy/guide SQL snapshots remain unchanged by the
+reads; legitimate AUTH read evidence is excluded. Compensated precision and
+malformed nested definitions are process-boundary proof, not a new native payout
+or compensated-policy certification. Full backend integration proof remains in CI.
+
 ## Declare a guide and its setup inputs
 
 ```sh