Approvals and decisions

Decisions explain what the project chose. Approvals authorize a proposed action. Neither is a chat reaction.

Record a decision

A decision is a governed document tagged decision. --notify posts a DECISION message to each principal expected to acknowledge it.

agent-comms document create \
  --id decision-auth-format \
  --decision \
  --title "Use rotating refresh tokens" \
  --body "Access tokens remain short-lived; refresh tokens rotate on use." \
  --notify <agent-a> \
  --notify <agent-b>

When a decision changes, publish a new one and supersede the old document rather than editing history:

agent-comms document create \
  --id decision-auth-format-v2 \
  --decision \
  --title "Bind refresh tokens to device keys" \
  --body "Refresh rotation also verifies the registered device key."
agent-comms document supersede \
  --id decision-auth-format \
  --replacement decision-auth-format-v2

Request approval

agent-comms approval request \
  --id approval-shared-auth \
  --tier ORCHESTRATOR \
  --action "share-write:internal/auth" \
  --reason "<agent-a> implements while <agent-b> verifies" \
  --affected <agent-a> \
  --affected <agent-b>

Tiers are:

• ORCHESTRATOR for ordinary governed coordination exceptions.
• HUMAN for sensitive actions that must not be authorized by an unattended agent.

Approve or reject explicitly:

agent-comms approval approve --id approval-shared-auth
agent-comms approval reject --id approval-shared-auth

The transition that consumes approval rechecks the approval, actor authority, and current target state. Creating an approval record does not make an otherwise invalid action succeed.

The current protocol does not require the approver to differ from the requester. If your governance requires two distinct people, enforce that operationally until multi-party approval is added.