Review a proposal without confusing approval with execution

Before you start.

Set up your workspace

Use governance:read for the first request. The later negative-decision test needs separately agreed governance:decide and the signed-request profile; it is not run by the read-only example. If no test proposal exists, arrange one with the owner rather than silently creating it.

Examples are illustrative test plans, not customer results. Use only agreed access and non-production material.

Make the first read, then interpret it.

GET /api/v2/governance/proposals

Use a trusted terminal and a scoped, non-production read credential supplied by your approved credential manager. The command sends the authorization header through standard input, not a literal token in the command. Do not enable shell tracing or paste the response into a public report; returned metadata may be private.

# Your approved credential manager must set HC_GUIDE_TOKEN first.
: "${HC_GUIDE_TOKEN:?Set a scoped test credential in this trusted terminal}"
printf 'Authorization: Bearer %s\n' "$HC_GUIDE_TOKEN" | \
  curl --fail-with-body --silent --show-error --header @- \
  'https://api.hybrid-chain.com/api/v2/governance/proposals'

Read the response deliberately

• Select the actual returned proposal reference and follow the documented proposal_uuid detail path.
• Record the returned state, authority, approvals and retained evidence; missing evidence stays unresolved.
• Visibility is not decision eligibility, and a decision is not proof of execution.

Request paths, authentication modes and named response fields were checked against the published OpenAPI contract. Values are deliberately not filled with a fake live response. Follow the operation links for current schemas and errors.

The workflow at a glance.

Work through one useful case.

A release team wants to change a contract authority. Operations and security must review the same proposed change, while the deployment team needs to know what that review does—and does not—allow it to do next.

Keep one working record throughout

Select one existing test proposal for a contract authority change. Create a decision table with proposal reference, reviewed content/version, eligible role, decision reference and receiving workflow. Leave signatures and deployments in separate columns.

1. 01

   Define the decision before opening the record

   Write down the resource, intended change, responsible owner, and applicable policy. Select an existing proposal visible to the caller. Avoid vague requests such as “approve the release” when reviewers need to know the exact artifact or authority arrangement involved.

   Do this

   1. Write the exact intended change and its owner before choosing the proposal.
   2. Read the visible proposal collection and select the matching test record.
   3. Compare the returned resource and review context with the intended change, not just its display name.

   Expected result

   Your table refers to one identifiable decision with a named owner and an explicit subject.

   If your result is different

   If the proposal cannot be found, check access and test provisioning. Do not copy a production proposal into the tutorial without authorization.

   Result: The evaluation concerns one identifiable proposed change, with a named owner and explicit review scope.

2. 02

   Read the proposal and its authority context

   Inspect the proposal detail for its state, authority, approvals, and retained evidence. Compare the returned context with the team's intended change. Missing evidence should remain an open review issue rather than being replaced by assumptions from an email or another proposal.

   Do this

   1. Read the proposal detail and copy only the relevant version, state and evidence references privately.
   2. Map each reviewer to the role and policy that makes that reviewer eligible.
   3. Mark absent supporting evidence as an open item instead of accepting an unrelated email as the same record.

   Expected result

   Every reviewer can identify the content and authority they are being asked to assess.

   If your result is different

   If the returned schema is open or fields differ, use the current detail reference and actual response; do not retrofit it to a fabricated example.

   Result: Reviewers are discussing the same record and can explain which information they actually inspected.

3. 03

   Test eligibility and changed content

   Plan an ineligible-reviewer case and a changed-proposal case in the authorized test workflow. Only exercise decision writes after confirming governance:decide and the exact signed-request contract. Capture the real accepted or rejected result; this guide does not prescribe a universal voting threshold.

   Do this

   1. Agree an ineligible-reviewer case and a changed-content case with the test owner.
   2. Use the authorized signed decision client only after checking its scope, signature and idempotency requirements.
   3. Record accepted/rejected outcomes against the exact reviewed content; mark tests not run when authority is unavailable.

   Expected result

   The worksheet contains observed eligibility/version behavior or an explicit test blocker, not a universal voting assumption.

   If your result is different

   For a lost decision response, inspect the existing proposal/decision state and retry semantics before issuing another logical decision.

   Result: The team has observed evidence for its eligibility boundary and knows when a fresh review is required.

4. 04

   Define the receiving workflow's checks

   Identify the owner of any later contract preparation, wallet signing, or execution operation. That workflow must check its own current authority and readiness. Keep the reviewed proposal reference alongside the separately observed result; do not synthesize a completed transaction from approval history.

   Do this

   1. Name the workflow that would consume the proposal and the authority it must check independently.
   2. Record whether preparation, signing or deployment evidence actually exists.
   3. Finish the handoff with remaining dependencies and a precise definition of completion.

   Expected result

   A receiving team can use the decision evidence without mistaking it for a completed operation.

   If your result is different

   If the receiving operation is disabled, leave it disabled. A proposal approval cannot activate a planned API.

   Result: The handoff checklist clearly separates a recorded decision from any later operation and its outcome.

Test where the workflow stops.

A useful pilot explains failure as clearly as success. Record what you observed rather than presenting these expected checks as completed results.

A reader attempts to act as an approver

Inspect the eligibility result under the current policy; visibility alone must not be treated as decision authority.

The reviewed content changes

Recheck applicable decisions and policy; do not apply an old decision to an unreviewed change.

A decision response is lost

Follow the documented idempotency and state-reconciliation behavior rather than creating an unrelated second decision.

The receiving workflow is unavailable

Keep the approved proposal distinct from the operation that has not happened.

Your acceptance checklist.

Retain the environment, contract version, test time, redacted observations, unresolved dependencies, and responsible reviewer in your private evaluation report.

Keep the contract close.

These links point to documented operations, not executable controls. Check the current request schema, scopes, errors, and implementation status before using them. No credentials or live customer responses are embedded in this guide.

Read the published OpenAPI definition

Choose your next step.

Keep your worksheet and error notes. Continue with the next technical exercise using the same reference trail, and mark any stage that remains untested rather than treating the checklist as a completed deployment.

Need help with access or an unavailable integration? Contact the team with a redacted error and the guide step. Never send credentials or private records.